Integration Guidelines for Partner Relationship Management

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

Service Provider Service

 

Web Service

The Service Provider Service Web Service provides the Service Provider with operations for handling Service Provider Accounts, Application Accounts, and Applications Instances.

Interface: SpService

The endpoint for this interface is: http://<host>:<port>/prm_sp/services/SpService

Where the value for host and port depend on the Oracle Communications Services Gatekeeper deployment.

deleteSpAccountReq

Makes a request to delete the Service Provider Account. Before a Service Provider Account can be deleted, it must be in the INACTIVE state. The request must be approved before the Service Provider Account is deleted. This is done by the Operator, using deleteSpAccountRes,

Table 7-1 deleteSpAccountReq()
Parameter Name
Type
Description
Input
   
No input parameters.
   
Returns
   
deleteSpAccountReqReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the Service Provider Account is not in state INACTIVE, this exception is thrown.

deactivateSpAccount

Deactivates the Service Provider Account, which changes the state of the account to INACTIVE.

Table 7-2 deactivateSpAccount()
Parameter Name
Type
Description
Input
   
No input parameters
   
Returns
   
deactivateSpAccountReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the Service Provider Account is not in an appropriate state to allow the account to be deactivated, this exception is thrown.

activateSpAccount

Activates the Service Provider Account. which changes the state of the account to ACTIVE.

Table 7-3 activateSpAccount()
Parameter Name
Type
Description
Input
   
No input parameters.
   
Returns
   
activateSpAccountReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the Service Provider Account is not in an appropriate state to allow the account to be activated, this exception is thrown.

getSpAccount

Retrieves details about the Service Provider Account. The details include contact details and CRM/PRM application-defined properties in the form of name-value pairs.

Table 7-4 getSpAccount()
Parameter Name
Type
Description
Input
   
No input parameters.
   
Returns
   
getSpAccountReturn
tns1:SpAccount
Data structure with details on the Service Provider account. See SpAccount.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getSpAccountState

Retrieves the state of the Service Provider Account.

Table 7-5 getSpAccountState()
Parameter Name
Type
Description
Input
   
No input parameters.
   
Returns
   
getSpAccountStateReturn
tns1:State
Information of the state of the Service Provider Account. See State.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

registerAppAccountReq

Requests registration of an Application Account for the Service Provider Account. This request must be approved by the Operator: see registerAppAccountRes.

Table 7-6 registerAppAccountReq(appAccountId, app)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
app
tns1:AppAccount
Data structure with details about the Application Account, including CRM/PRM application-defined properties in the form of name-value pairs. See AppAccount.
Returns
   
registerAppAccountReqReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
   

deleteAppAccountReq

Requests deletion of an Application Account associated with the Service Provider Account. The request must be approved by the Operator before the Application Account is delete. This is done using deleteAppAccountRes. The Application Account must be in state INACTIVE in order for this call to be accepted.

Table 7-7 deleteAppAccountReq(appAccountId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
Returns
   
deleteAppAccountReqReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
   

updateSpAccountReq

Requests an update of the Service Provider Account with new data.

Table 7-8 updateSpAccount(spAccountId, spAccount)
Parameter Name
Type
Description
Input
   
spAccount
tns1:SpAccount
Data structure with details on the Service Provider Account, including CRM/PRM application-defined properties in the form of name-value pairs. See SpAccount.
Returns
   
updateSpAccountReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
   

updateAppAccountReq

Requests an update to an Application Account associated with the Service Provider with new data.

Table 7-9 updateAppAccount(appAccountId, appAccount)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
app
tns1:AppAccount
Data structure with details on the Application Account, including CRM/PRM application-defined properties in the form of name-value pairs. See AppAccount.
Returns
   
updateAppAccountReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
   

updateAppInstGroupReq

Requests an update on an Application Instance. The request must be approved by the Operator. See updateAppInstGroupRes.

Table 7-10 updateAppInstGroup(appAccountId, appInstGroupId, appInstGroup)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
appInstGroup
tns1:AppInstGroup
Data-structure with the Application Instance CRM/PRM application-defined properties in the form of name-value pairs. See AppInstGroup.
Returns
   
updateAppInstGroupReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
   

deleteAppInstGroupReq

Requests a deletion of an Application Instance. The request must be approved by the Operator. This is done using deleteAppInstGroupRes,

Table 7-11 deleteAppInstGroupReq(appAccountId, appInstGroupId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
Returns
   
deleteAppInstGroupReqReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
 
n.
INVALID_STATE
   

listAppAccounts

Lists all Application Account IDs for the Service Provider. The result is filtered based on the state of the Application Account

Table 7-12 listAppAccounts(state)
Parameter Name
Type
Description
Input
   
state
tns1:State
Indicates the states on which states to filter the result. State.
Returns
   
listAppAccountsReturn
Array of xsd:string
A list of IDs of Application Accounts.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getAppAccount

Retrieves details about a specific Application Account. The operation returns a data structure with details on the Application Account, including CRM/PRM application-defined properties in the form of name-value pairs.

Table 7-13 getAppAccount(appAccountId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
Returns
   
getAppAccountReturn
tns1:AppAccount
Data structure with details about the Application Account. See AppAccount.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getAppAccountState

Retrieves the state of a specific Application Account.

Table 7-14 getAppAccountState(appAccountId
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
Returns
   
getAppAccountStateReturn
tns1:State
Information on the state of the Application Account. See State
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

activateAppAccount

Activate an Application Account, which changes the state of the account to ACTIVE. The current state of the account must be INACTIVE.

Table 7-15 activateAppAccount(appAccountId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
Returns
   
activateAppAccountReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the Application Account is not in an appropriate state to allow the account to be activated, this exception is thrown.

deactivateAppAccount

Deactivates an Application Account, which changes the state of the account to INACTIVE. The current state of the account must be ACTIVE.

Table 7-16 deactivateAppAccount(appAccountId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
Returns
   
deactivateAppAccountReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the state of the Application Account does not allow the account to be deactivated, this exception is thrown.

activateAppInstGroup

Activates an Application Instance, which changes the state of the instance to ACTIVE.

Table 7-17 activateAppInstGroup(appAccountId, appInstGroupId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
Returns
   
activateAppInstGroupReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the Application Instance is not in an appropriate state to allow the account to be activated, this exception is thrown.

getAppInstGroupState

Gets the state of an Application Instance.

Table 7-18 getAppInstGroupState(appAccountId, appInstGroupId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
Returns
   
getAppInstGroupStateReturn
tns1:State
The state of the Application Instance. See State.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

deactivateAppInstGroup

Deactivates an Application Instance, which changes the state of the group to INACTIVE.

Table 7-19 deactivateAppInstGroup(appAccountId, appInstGroupId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
Returns
   
deactivateAppInstGroupReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the Application Instance is not in an appropriate state to allow the account to be deactivated, this exception is thrown.

registerAppInstGroupReq

Requests the registration of an Application Instance for a specific Application Account. When this request has been approved by the Operator, see registerAppInstGroupRes, an application has all credentials necessary to be authenticated on the traffic interfaces of the Oracle Communications Services Gatekeeper.

Table 7-20 registerAppInstGroupReq(appAccountId, appInstGroupId, appInstGroup, password)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance to be registered.
appInstGroup
tns1:AppInstGroup
The CRM/PRM application-defined properties in the form of name-value pairs. See AppInstGroup.
password
xsd:string
The password the application will use when authenticating on Oracle Communications Services Gatekeeper
Returns
   
registerAppInstGroupReqReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
   

deactivateAppInstGroup

Deactivate an Application Instance. Change the state of the instance to INACTIVE.

Table 7-21 deactivateAppInstGroup(appAccountId, appInstGroupId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
Returns
   
deactivateAppInstGroupReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   
INVALID_STATE
 
If the Application Instance is not in an appropriate state to allow the account to be activated, this exception is thrown.

listAppInstGroups

Lists all Application Instances for an Application Account. Filtering is possible on the state of the Application Instance

Table 7-22 listAppInstGroups(appAccountId, state)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
state
tns1:State
Indicates which states to filter the result on. See State
Returns
   
listAppInstGroupsReturn
Array of xsd:string
A list of all Service Application Instance IDs matching the given criteria.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getAppInstGroup

Retrieves details about a specific Application Instance.

Table 7-23 getAppInstGroup(appAccountId, appInstGroupId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
Returns
   
getAppInstGroupReturn
tns1:AppInstGroup
Data structure with details about the Application Instance. See AppInstGroup.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getSpAccountSla

Deprecated. Use getSpAccountSlaByType.

Note: The new mechanism (getSpAccountSlaByType) adds a parameter, slaType. Requests made using getSpAccountSla have this parameter hardcoded to a value of service_provider.

Retrieves the Service Provider SLA of the currently logged in service provider.

Table 7-24 getSpAccountSla()
Parameter Name
Type
Description
Input
   
No input parameters.
   
Returns
   
getSpAccountSlaReturn
xsd:string
The Service Provider SLA.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getSpAccountSlaByType

Retrieves an SLA of a given type for the Service Provider Account.

Table 7-25 getSpAccountSlaByType(slaType)
Parameter Name
Type
Description
Input
   
slaType
xsd:string
The SLA type to retrieve.
Use:
  • service_provider
  • system:geo_service_provider
  • service_provider_node
  • a custom SLA type ID
For information on the different types, see section Managing SLAs in Managing Accounts and SLAs.
Returns
   
getSpAccountSlaByType
xsd:string
The SLA.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getAppAccountSla

Deprecated. Use getAppAccountSlaByType.

Note: The new mechanism (getAppAccountSlaByType) adds a parameter, slaType. Requests made using getAppAccountSla have this parameter hardcoded to a value of application.

Retrieves the Application-level SLA.

Table 7-26 getAppAccountSla(appAccountId)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The Application Account to retrieve the SLA for.
Returns
   
getAppAccountSlaReturn
xsd:string
The application-level SLA.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

getAppAccountSlaByType

Retrieves an SLA of a given type for the Application Account.

Table 7-27 getAppAccountSlaByType(slaType, appAccountId)
Parameter Name
Type
Description
Input
   
slaType
xsd:string
The SLA type to retrieve.
Use:
  • application
  • system:geo_application
  • a custom SLA type ID
For information on the different types, see section Managing SLAs in Managing Accounts and SLAs.
appAccountId
xsd:string
The Application Account to retrieve the SLA for.
Returns
   
getAppAccountSlaReturn
xsd:string
The application-level SLA.
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

setAppInstGroupPassword

Set the password associated with an Application Instance. This password is a part of the credentials an application uses to be authenticated on the traffic interfaces exposed by Oracle Communications Services Gatekeeper.

.

Table 7-28 setAppInstGroupPassword(appAccountId, appInstGroupId, newPassword)
Parameter Name
Type
Description
Input
   
appAccountId
xsd:string
The ID of the Application Account.
appInstGroupId
xsd:string
The ID of the Application Instance.
newPassword
xsd:string
The new password.
Returns
   
setAppInstGroupPasswordReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

changeSpAccountPassword

Change the Service provider Account password. This password is the password the Service Provider use to login to the Service Provider part of the Partner Management Interfaces exposed by Oracle Communications Services Gatekeeper.

.

Table 7-29 changeSpAccountPassword(oldPassword, newPassword
Parameter Name
Type
Description
Input
   
oldPassword
xsd:string
The current password.
newPassword
xsd:string
The new password.
Returns
   
changeSpAccountPasswordReturn
void
 
Possible Exceptions
   
ACCESS_DENIED
   
CommonException
   

Exceptions

ACCESS_DENIED

Exceptions of this type are raised when the operation is not permited. The user does not have adequate privileges to perform the operation.

CommonException

This exception is raised when the login session has expired (BC only) or there are communication problems with the underlying platform.

INVALID_STATE

The operation is not valid since the operation results in a state transition, and the transition from the current state to the state the operation results in is not allowed.

Data types

AppAccount

Description of an Application Account.

Table 7-30 appAccount
Element name
Datatype
Description
Name
xsd:string
Descriptive name of the Application Account.
Description
xsd:string
Short description of the Application Account.
Properties
impl:ArrayOf_tns1_Property
CRM/PRM application-defined name value pairs. See Property.

AppInstGroup

Container for the CRM/PRM application-defined properties.

Table 7-31 AppGroup
Element name
Datatype
Description
Name
xsd:string
Descriptive name of the Application Instance.
Description
xsd:string
Short description of the Application Instance.
SLA
xsd:string
The SLA for the Application Instance.
Is always “1” as the SLA feature is no longer used.
Properties
mpl:ArrayOf_tns1_Property
CRM/PRM application-defined properties. Name-value pairs. See Property.

Property

Array of name-value pairs. This datatype is used in several other datatypes specific for this interface. The properties are accessible from the Service Provider interface and the Operator interface, so they can be used for communicating information between the Service Provider and the Operator

Table 7-32 Property
Element name
Datatype
Description
Name
xsd:string
Name of the property, with the value defined in Value. Unique with the array.
Value
xsd:string
The data associated with Name.

SpAccount

Description of a Service Provider Account, including contact details.

Table 7-33 appAccount
Element name
Datatype
Description
Name
xsd:string
Name of the Service Provider.
Address
xsd:string
Address of the Service Provider.
EMailAddress
xsd:string
E-mail address of the Service Provider.
ContactPerson
xsd:string
Contact person at the Service provider.
PhoneNumber
xsd:string
Phone number to the Service Provider.
Properties
mpl:ArrayOf_tns1_Property
CRM/PRM application-defined name value pairs. See Property.

State

Defines the state of a Service Provider Account, Service Provider Group, Application Account, Application Group, or Application Instance. Enumeration.

SeeAccount States for more information about states, and transitions between different states.

Table 7-34 State
Element name
Datatype
Description
REGISTERED
xsd:string
The account or group is has been registered. The Operator must respond to this registration request.
ACTIVE
xsd:string
Normal mode.
INACTIVE
 
No traffic is allowed through the Oracle Communications Services Gatekeeper when the account or group is in this state.
UPDATE_PENDING
 
There is a pending update request. The request must be responded to by the Operator.
DELETE_PENDING
 
There is a pending delete request on the account or group. The request must be responded to by the Operator
LOCKED
 
Only valid for an Applicator Instances. For backwards compatibility only. The group can be locked due to too many consecutive failed login attempts from an application.


  Back to Top       Previous  Next