Glossary Item Box

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

# DelegatedRights Interface

For a list of all methods on this Web service interface see DelegatedRights Methods.

#### Remarks

The web method (there is only one - GsoDelegateRigts) on this interface takes an input string and returns an output string. These strings should be escaped XML documents that conform to the DelegateRights service XSDs. These XSDs are not included in the WSDL for ease of client development and versioning.
A developer who is writing to this interface should use both the WSDL and the XSDs to fully specify client behaviour. The XSDs are specified in the documentation for the Web methods – i.e. GsoDelegatedRights.

The WSDL is listed below. It can also be acccessed online (see Calling the DelegatedRequest SOAP Interface).

#### Authentication and Authorisation

The service uses WS-Security to authenticate originators of SOAP requests. Calls to methods on the DelegatedRights SOAP Interface must be made using a DRM user registered with the Gateway. A DRM user's credential can be based on either a User ID/password (UsernameToken) or a certificate (X509Security token) – it is included in the SOAP header.

For more details see Calling GsoDelegateRights using a UsernameToken and Calling GsoDelegateRights using an X509SecurityToken

#### SOAP Faults

The Gateway can return 2 different types of SOAP faults.

- Security Exceptions: All security exceptions are defined in the WS standards. To view the security exceptions that the Gateway can raise see the following section WS-* Exceptions exposed on Gateway
- Gateway Exceptions: All business rule violations and internal errors will be returned back to the client as Gateway Exceptions

All Gateway Business Error SOAP faults will be of the following format:

    <soap:Body>
      <soap:Fault>
          <faultcode>soap:Server</faultcode>
          <faultstring>Business Error</faultstring>
          <faultactor>urn:GSO-System-Services:external:1.65:GatewaySecurityTokenService</faultactor>
          <detail>
            <GatewayDetails xmlns="urn:GSO-System-Services:external:1.65:SoapException">
              <ErrorNumber>5001</ErrorNumber>
              <Message>Input Xml failed schema validation</Message>
              <RequestID>44df-faa6fd4c5fc</RequestID>
            </GatewayDetails>
          </detail>
      </soap:Fault>
    </soap:Body>

The SOAP fault is a standard schema, extended with the GatewayDetails node. The faultstring should be 'Business Error' for errors that occur during normal operation. The contents of GatewayDetails are as follows:

- ErrorNumber: Errors above 2000 are business rule errors and would usually indicate that the client is making an invalid request. The details of the expected errors from each of the methods are detailed in the method documentation. Errors that can occur on any method call are detailed below
- Message: this includes detail of the cause of the error. This may vary between instances of a given error number. This node is optional and will only appear on Business Errors
- RequestID: an id that maps to entries in the logs on the Gateway server. If a serious error is encountered then this can be useful for diagnosing the cause

The following lists the set of general errors that could occur in any WebMethod call.

SOAP Fault Error Number | Description
--- | ---
1000 | Unexpected System Error. This indicates a serious internal error on the Gateway.
1001 | Unexpected Internal Error. This indicates that there is a problem with the Gateway. The client should try again later.
1501 | Authorisation Error. The user credentials are valid but the user does not have permission to perform the requested function, for one of the following reasons: The user is not an Admin user The Admin user is not enrolled for an admin service which manages the target service The Admin user is enrolled in an appropriate admin service, but that admin service does not permit the specific action requested
1506 | SecurityToken Error. The SecurityToken can only be used once.
5001 | Bad Input Xml. The input document failed schema check. The namespace used may be incorrect for the method called, the document may be badly formed, or violate the schema. Check details of the Message section of this error for the specific failure.
5002 | Input XML fails business validation Once the input XML has been validated by the method's XML schema, it can still be rejected by the business logic as being incomplete or inconsistent.

WSDL for the WS-* compliant Web Service:

    <?xml version="1.0" encoding="utf-8" ?>
    <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://www.gateway.gov.uk/soap/2007/02/delegatedrights" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" targetNamespace="http://www.gateway.gov.uk/soap/2007/02/delegatedrights" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
      <wsdl:types>
        <s:schema elementFormDefault="qualified" targetNamespace="http://www.gateway.gov.uk/soap/2007/02/delegatedrights">
          <s:element name="GsoDelegateRights">
            <s:complexType>
              <s:sequence>
                <s:element minOccurs="0" maxOccurs="1" name="inputXml" type="s:string" />
              </s:sequence>
            </s:complexType>
          </s:element>
          <s:element name="GsoDelegateRightsResponse">
            <s:complexType>
              <s:sequence>
                <s:element minOccurs="0" maxOccurs="1" name="outputXml" type="s:string" />
              </s:sequence>
            </s:complexType>
          </s:element>
        </s:schema>
      </wsdl:types>
      <wsdl:message name="GsoDelegateRightsSoapIn">
        <wsdl:part name="parameters" element="tns:GsoDelegateRights" />
      </wsdl:message>
      <wsdl:message name="GsoDelegateRightsSoapOut">
        <wsdl:part name="parameters" element="tns:GsoDelegateRightsResponse" />
      </wsdl:message>
      <wsdl:portType name="DelegatedRightsSoap">
        <wsdl:operation name="GsoDelegateRights">
          <wsdl:input message="tns:GsoDelegateRightsSoapIn" />
          <wsdl:output message="tns:GsoDelegateRightsSoapOut" />
        </wsdl:operation>
      </wsdl:portType>
      <wsdl:binding name="DelegatedRightsSoap" type="tns:DelegatedRightsSoap">
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="GsoDelegateRights">
          <soap:operation soapAction="http://www.gateway.gov.uk/soap/2007/02/delegatedrights/GsoDelegateRights" style="document" />
          <wsdl:input>
            <soap:body use="literal" />
          </wsdl:input>
          <wsdl:output>
            <soap:body use="literal" />
          </wsdl:output>
        </wsdl:operation>
      </wsdl:binding>
      <wsdl:binding name="DelegatedRightsSoap12" type="tns:DelegatedRightsSoap">
        <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="GsoDelegateRights">
          <soap12:operation soapAction="http://www.gateway.gov.uk/soap/2007/02/delegatedrights/GsoDelegateRights" style="document" />
          <wsdl:input>
            <soap12:body use="literal" />
          </wsdl:input>
          <wsdl:output>
            <soap12:body use="literal" />
          </wsdl:output>
        </wsdl:operation>
      </wsdl:binding>
      <wsdl:service name="DelegatedRights">
        <wsdl:port name="DelegatedRightsSoap" binding="tns:DelegatedRightsSoap">
          <soap:address location="http://gg1reiis01vs.ggdom01vs.local/soap/2007/02/delegatedrights/delegatedrights.asmx" />
        </wsdl:port>
        <wsdl:port name="DelegatedRightsSoap12" binding="tns:DelegatedRightsSoap12">
          <soap12:address location="http://gg1reiis01vs.ggdom01vs.local/soap/2007/02/delegatedrights/delegatedrights.asmx" />
        </wsdl:port>
      </wsdl:service>
    </wsdl:definitions>

#### XSDs used by Web service

GsoCore.xsd and GsoCore210.xsd

© Crown Copyright 2008. All rights reserved