Glossary Item Box

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

# GatewaySoapPublic.GsoGetServiceInfo (1.6.5, 1.6.6 and 1.6.7) Method

This method returns detailed information about the specified service. This includes Identifier, Known Fact and Service Transaction information.

(Note this version of GsoGetUserDetails should only be used for portals/applications built for releases 1.6.5, 1.6.6 and 1.6.7 of the Gateway.)

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

#### Parameters

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

#### Remarks

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

- ServiceName: The name of the service you want to get information on

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:GsoGetServiceInfoXmlInput" 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:GsoGetServiceInfoXmlInput" elementFormDefault="qualified" attributeFormDefault="unqualified" version="2.0">
      <xs:import namespace="urn:GSO-System-Services:external:1.65:GsoCore" />
      <xs:element name="GsoGetServiceInfoXmlInput">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ServiceName" type="core:ServiceNameTYPE" />
          </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:GsoGetServiceInfoXmlOutput" xmlns="urn:GSO-System-Services:external:1.65:GsoGetServiceInfoXmlOutput" 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="GsoGetServiceInfoXmlOutput">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ServiceOwner" type="core:ServiceOwnerTYPE" />
            <xs:element name="ServiceName" type="core:ServiceNameTYPE" />
            <xs:element name="ServiceDescription" type="core:TextDataTYPE" />
            <xs:element name="MinimumTSchemeLevel" type="core:TSchemeLevelTYPE" />
            <xs:element name="ServiceHelpTel" type="core:TelephoneNumberTYPE" />
            <xs:element name="HelpText" type="core:TextDataTYPE" />
            <xs:element name="HelpUrl" type="core:TextDataTYPE" />
            <xs:element name="ServiceHelpText" type="core:TextDataTYPE" />
            <xs:element name="ServiceHelpUrl" type="core:TextDataTYPE" />
            <xs:element name="TermsAndConditionsUrl" type="core:TextDataTYPE" />
            <xs:element name="ServiceTransactions">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="ServiceTransaction" type="core:ServiceTransactionTYPE" minOccurs="0" maxOccurs="unbounded" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="ClientServices" minOccurs="0">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="ServiceName" type="core:ServiceNameTYPE" minOccurs="0" maxOccurs="unbounded" />
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="Identifiers">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="Identifier" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                      <xs:attribute name="Type" type="core:IdentifierTypeTYPE" use="required" />
                      <xs:attribute name="DisplayMask" type="core:IdentifierTypeMaskTYPE" use="required" />
                      <xs:attribute name="EmailMask" type="core:IdentifierTypeMaskTYPE" use="required" />
                    </xs:complexType>
                  </xs:element>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="ServiceRules">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="ServiceRule" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                      <xs:attribute name="ServiceRuleName" type="core:ServiceRuleNameTYPE" use="required" />
                      <xs:attribute name="Seq" type="core:ServiceRuleSequenceTYPE" use="required" />
                      <xs:attribute name="RegularExpression" type="core:ServiceRuleRegularExpressionTYPE" use="required" />
                      <xs:attribute name="InputFieldType" type="core:InputFieldTypeTYPE" use="required" />
                      <xs:attribute name="InputFieldSize" type="core:InputFieldSizeTYPE" use="required" />
                      <xs:attribute name="TextPrompt" type="core:TextDataTYPE" use="required" />
                      <xs:attribute name="InputHint" type="core:TextDataTYPE" use="required" />
                    </xs:complexType>
                  </xs:element>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
            <xs:element name="ServiceRuleGroups">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="ServiceRuleGroup" minOccurs="0" maxOccurs="unbounded">
                    <xs:complexType>
                      <xs:sequence>
                        <xs:element name="ServiceRule" type="core:ServiceRuleNameTYPE" maxOccurs="unbounded" />
                      </xs:sequence>
                      <xs:attribute name="name" type="core:ServiceRuleGroupNameTYPE" use="required" />
                    </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

The specified service must be in an Active state and the calling credential must be eligible to view the service.

#### Method Steps

This method performs the following steps:

- Gets the basic service information
- Checks that the registration category of the calling credential is supported by the service
- Checks that the authentication level of the calling credential meets the service's minimum required authentication level
- Gets detailed information about the service.
- Returns the service information

#### 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'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
The Credential must NOT be of the following type: Admin | 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 must be in the following roles: User | 8026: The credential has the wrong type of role The credential has the wrong type of role to be used with this function. e.g. The credential is an assistant where a peer is required.

#### 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. Note: Additionally, to support distributed known facts (introduced in release 1.6.8 of the Gateway): if a service uses distributed known facts t his exception will be raised.
3003 | The Service is not in an active state For this method to be executed the Service State has to be active.
8002 | The specified Credential does not exist If a method is given the details of a Credential that does not exist then this exception will be raised
8004 | The credential’s current authentication level is not high enough to perform this action The credential does not have a high enough authentication level to perform the requested action
13005 | The service is not valid for the registration category The registration profile can only be used for specific services. If a service is chosen that does not support this registration category then this exception will be thrown

#### 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"?>
    <GsoGetServiceInfoXmlInput xmlns="urn:GSO-System-Services:external:1.65:GsoGetServiceInfoXmlInput">
      <ServiceName>MOSW1</ServiceName>
    </GsoGetServiceInfoXmlInput>

The following is a sample of an output document:

    <?xml version="1.0" encoding="utf-8"?>
    <GsoGetServiceInfoXmlOutput RequestID="B2A72BD70D284013BB410800D0DCA4F6" xmlns="urn:GSO-System-Services:external:1.65:GsoGetServiceInfoXmlOutput">
      <ServiceOwner>MOSW</ServiceOwner>
      <ServiceName>MOSW1</ServiceName>
      <ServiceDescription>MOSW Test Service 1</ServiceDescription>
      <MinimumTSchemeLevel>SomeAssurance</MinimumTSchemeLevel>
      <ServiceHelpTel>0118 909 0001</ServiceHelpTel>
      <HelpText>About MOSW Test Service 1</HelpText>
      <HelpUrl>www.gso.eval/TestServiceURLs/HowToUseTestServices.htm</HelpUrl>
      <ServiceHelpText>Using the MOSW Test Service 1</ServiceHelpText>
      <ServiceHelpUrl>www.gso.eval/TestServiceURLs/HowToUseTestServices.htm</ServiceHelpUrl>
      <TermsAndConditionsUrl />
      <ServiceTransactions>
        <ServiceTransaction>MOSWTSC1</ServiceTransaction>
        <ServiceTransaction>MOSWTSC1A</ServiceTransaction>
        <ServiceTransaction>MOSWTSC1B</ServiceTransaction>
      </ServiceTransactions>
      <Identifiers>
        <Identifier Type="MOSW1Reference" DisplayMask="*AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" EmailMask="" />
      </Identifiers>
      <ServiceRules>
        <ServiceRule ServiceRuleName="MOSW1Reference" Seq="0" RegularExpression="/^\w\W0,9}$/" InputFieldType="text" InputFieldSize="9" TextPrompt="MOSW Test Service 1 Reference" InputHint="e.g. 123456789" />
        <ServiceRule ServiceRuleName="MOSW1PostCode" Seq="1" RegularExpression="/^\w\W{0,10}$/" InputFieldType="text" InputFieldSize="10" TextPrompt="MOSW Test Service 1 Post Code" InputHint="e.g. AB12 3CD" />
      </ServiceRules>
      <ServiceRuleGroups>
        <ServiceRuleGroup name="Group1">
          <ServiceRule>MOSW1Reference</ServiceRule>
          <ServiceRule>MOSW1PostCode</ServiceRule>
        </ServiceRuleGroup>
      </ServiceRuleGroups>
    </GsoGetServiceInfoXmlOutput>

#### See Also

Public Interface

© Crown Copyright 2008. All rights reserved