Application Development Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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)

  Back to Top       Previous  Next