# Application Development Guide

# Access Web Service (deprecated)

Note: | The Access Web Service is not deployed in a standard installation.

Note: | It is deprecated and should only be used by older, existing applications, in order to provide a migration path for these applications. WebLogic Server Web Services security cannot be used when using the Access Web Service and must be turned off in Oracle Communications Services Gatekeeper to be able to use the Access Web Service.

The Access Web Service contains operations for establishing a session with Oracle Communications Services Gatekeeper, changing the application’s password, querying the amount of time remaining in the session, refreshing the session, and terminating the session.

Before an application can perform any operations on the Parlay X or Extended Web Services interfaces, a session must be established with Oracle Communications Services Gatekeeper. When a session is established, a session ID (loginTicket) is returned which must be used in each subsequent operation towards Oracle Communications Services Gatekeeper.

The loginTicket shall be present in the SOAP Header element Security, see below. Once the login ticket is acquired, it must be sent in the SOAP header together with a username/password combination each time a Web Service method is invoked. See Examples.

## Endpoint

The WSDL for the Access Web Service can be found at `http://<host:port>/parlayx21/access/Access`

where host and port depend on the Oracle Communications Services Gatekeeper deployment.

## Interface: Access

Operations to establish a session, change a password, get the remaining lifetime of a session, refresh a session and destroy a session.

### Operation: applicationLogin

Logs the application into the Oracle Communications Services Gatekeeper and retrieves a login ticket. This login ticket represents the session and must be added to the SOAP header of every subsequent request that the application makes to the Oracle Communications Services Gatekeeper.

In most cases, the login ticket is only valid for a certain time interval, set by the operator. Once the time period has expired, the application has a second operator-set time period to refresh the login ticket. Until the ticket is refreshed, the application can not make any other requests. The operation used to refresh the ticket is refreshLoginTicket, see Operation: refreshLoginTicket. If the ticket is not refreshed during this second period, the session is destroyed, and the application must log back in.

#### Input message: applicationLoginRequest

Part name | Part type | Optional | Description
--- | --- | --- | ---
serviceProvider | s1:String | N | ID of the service provider as given by the operator or the service provider.
application | s1:String | N | ID of the application as given by the operator or the service provider.
applicationInstanceGroup | s1:String | N | ID of the application instance group as given by the operator or the service provider.
password | s1:String | N | Password for the application as given by the operator or the service provider. Note that this may also have been changed by the by the application provider.

#### Output message: applicationLoginResponse

Part name | Part type | Optional | Description
--- | --- | --- | ---
applicationLoginReturn | s1:string | N | ID of the login-session. This ID is used for each request towards Oracle Communications Services Gatekeeper. It must be included in the SOAP header of every subsequent request. If an application logs in several times, the same ID is returned.

#### Referenced faults

AccessException

GeneralException

### Operation: applicationLogout

Logs an application out of the Oracle Communications Services Gatekeeper. Destroys the login session and the corresponding login ticket.

#### Input message: applicationLogoutRequest

Part name | Part type | Optional | Description
--- | --- | --- | ---
loginTicket | s1:string | N | ID of the login-session. The login ticket is retrieved when the application logs in or when it refreshes the login ticket.

#### Output message: applicationLogoutResponse

Part name | Part type | Optional | Description
--- | --- | --- | ---
- | - | - | -

#### Referenced faults

AccessException

GeneralException

### Operation: changeApplicationPassword

Changes the password for an application.

#### Input message: changeApplicationPasswordRequest

Part name | Part type | Optional | Description
--- | --- | --- | ---
loginTicket | s1:string | N | ID of the login-session. The login ticket is retrieved when the application logs in or when it refreshes the login ticket.
oldPassword | s1:string | N | The current password.
newPassword | s1:string | N | The new password.

#### Output message: changeApplicationPasswordResponse

Part name | Part type | Optional | Description
--- | --- | --- | ---
- | - | - | -

#### Referenced faults

AccessException

GeneralException

### Operation: getLoginTicketRemainingLifeTime

Reports the remaining amount of time the login ticket is valid.

#### Input message: getLoginTicketRemainingLifeTimeRequest

Part name | Part type | Optional | Description
--- | --- | --- | ---
sessionId | s1:string | N | ID of the login-session. The login ticket is retrieved when the application logs in or when it refreshes the login ticket.

#### Output message: getLoginTicketRemainingLifeTimeReturn

Part name | Part type | Optional | Description
--- | --- | --- | ---
getLoginTicketRemainingLifeTimeReturn | s1:int | N | The time until the login ticket expires. The time is given in minutes.

#### Referenced faults

AccessException

GeneralException

### Operation: refreshLoginTicket

Refreshes the login ticket. This refreshed login ticket must be provided in the SOAP header in all subsequent method calls. The login ticket can be refreshed for a limited, operator-set time interval after the previous login ticket has expired. If this time interval expires, the application must login again. Oracle Communications Services Gatekeeper expiration timers are reset, but the same login ticket is returned.

#### Input message: refreshLoginTicketRequest

Part name | Part type | Optional | Description
--- | --- | --- | ---
loginTicket | s1:string | N | The ID of an established session.
serviceProviderID | s1:string | N | ID of the service provider as given by the operator or the service provider.
applicationID | s1:string | N | ID of the application as given by the operator or the service provider.
applicationInstanceGroupID | s1:string | N | ID of the application instance group as given by the operator or the service provider.
password | s1:string | N | Password for the application as given by the operator or the service provider. Note that this may also have been changed by the by the application provider.

#### Output message: refreshLoginTicketResponse

Part name | Part type | Optional | Description
--- | --- | --- | ---
refreshLoginTicketReturn | s1:string | N | The refreshed ID of the login-session. This ID is used in each request towards Oracle Communications Services Gatekeeper. It must be included in the SOAP header of every subsequent request.

#### Referenced faults

AccessException

GeneralException

### Exceptions

#### AccessException

Exceptions of this type are raised when there are error conditions related to the Access Web Service. Other error conditions are reported using the exception GeneralException.

Part name | Part type | Optional | Description
--- | --- | --- | ---
exceptionMessage | xsd:string | Y | Description of exception.
errorCode | xsd:int | N | Code defining the exception.

#### GeneralException

Exceptions of this type are raised when the applications session has expired or there are communication problems with the underlying platform.

Part name | Part type | Optional | Description
--- | --- | --- | ---
exceptionMessage | xsd:string | Y | Description of exception.
errorCode | xsd:int | N | Code defining the exception.

## Examples

### Defining the security header

The loginTicket shall be present in the SOAP Header element Security, see below. Once the login ticket is acquired, it must be sent in the SOAP header together with a username/password combination each time a Web Service method is invoked.

The Access Web Service uses a security header described below.

The loginTicket is supplied in the Password attribute.

Listing 12-1 Access security header (example)

    <soapenv:Header>

      <ns1:Security ns1:Username="app:-2810834922008400383"

        ns1:Password="app:-2810834922008400383" soapenv:actor="wsse:PasswordToken"

        soapenv:mustUnderstand="1"     xmlns:ns1="http://localhost:6001/parlayx21/terminal_location/TerminalLocation">

      </ns1:Security>

    </soapenv:Header>

Below is an example of how to add an Access security header using Axis. The Username attribute must be present but is not used. The header must be added to the Web Service request.

Listing 12-2 Access security header (Axis)

    org.apache.axis.message.SOAPHeaderElement header =

     new org.apache.axis.message.SOAPHeaderElement(wsdlUrl, "Security", "");

    header.setActor("wsse:PasswordToken");

     header.addAttribute(wsdlUrl, "Username", ""+userName);

     header.addAttribute(wsdlUrl, "Password", ""+loginTicket);

     header.setMustUnderstand(true)