6 Service Provider Service

The Service Provider Service Web Service provides the Service Provider with operations for handling Service Provider Accounts, Application Accounts, and Applications Instances in Oracle Communications Services Gatekeeper.

Interface: SpService

The endpoint for this interface is:

http://host:port/prm_sp/services/SpService

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

deleteSpAccountReq

The deleteSpAccountReq method makes a request to delete the Service Provider Account. The request must be approved before the Service Provider Account is deleted. This is done by the operator, using "deleteSpAccountRes".

Input Parameters

This operation takes no input parameters.

Return Parameters

Void

Possible Exceptions

The possible exceptions are:

• ACCESS_DENIED

• CommonException

• INVALID_STATE: The Service Provider Account's state cannot be deleted. For a Service Provider Account to be deleted, it must be in the INACTIVE state.

deactivateSpAccount

Deactivates the Service Provider Account, which changes the state of the account to INACTIVE. This operation takes no input parameters.

Table 6-1 deactivateSpAccount()

Parameter Name	Type	Description
deactivateSpAccountReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception. The Service Provider Account is not in an appropriate state to allow the account to be deactivated.

activateSpAccount

Activates the Service Provider Account. which changes the state of the account to ACTIVE. This operation takes no input parameters.

Table 6-2 activateSpAccount()

Parameter Name	Type	Description
activateSpAccountReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception. The Service Provider Account is not in an appropriate state to allow the account to be activated.

getSpAccount

Retrieves details about the Service Provider Account. The details include contact details and customer relationship management (CRM)/partner relationship management (PRM) application-defined properties in the form of name-value pairs. This operation takes no input parameters.

Table 6-3 getSpAccount()

Parameter Name	Type	Description
getSpAccountReturn	tns1:SpAccount	Return parameter. A data structure with details on the Service Provider account. See "SpAccount".
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

getSpAccountState

Retrieves the state of the Service Provider Account. This operation takes no input parameters.

Table 6-4 getSpAccountState()

Parameter Name	Type	Description
getSpAccountStateReturn	tns1:State	Return parameter. Information of the state of the Service Provider Account. See "State".
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

registerAppAccountReq

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

Table 6-5 registerAppAccountReq(appAccountId, app)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
app	tns1:AppAccount	Input parameter. A data structure with details about the Application Account, including CRM/PRM application-defined properties in the form of name-value pairs. See "AppAccount".
registerAppAccountReqReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception

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 6-6 deleteAppAccountReq(appAccountId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
deleteAppAccountReqReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception

updateSpAccountReq

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

Table 6-7 updateSpAccount(spAccountId, spAccount)

Parameter Name	Type	Description
spAccount	tns1:SpAccount	Input parameter. The data structure with details on the Service Provider Account, including CRM/PRM application-defined properties in the form of name-value pairs. See "SpAccount".
updateSpAccountReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception

updateAppAccountReq

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

Table 6-8 updateAppAccount(appAccountId, appAccount)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
app	tns1:AppAccount	Input parameter. A data structure with details on the Application Account, including CRM/PRM application-defined properties in the form of name-value pairs. See "AppAccount".
updateAppAccountReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception

updateAppInstGroupReq

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

Table 6-9 updateAppInstGroup(appAccountId, appInstGroupId, appInstGroup)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
appInstGroup	tns1:AppInstGroup	Input parameter. A data-structure with the Application Instance CRM/PRM application-defined properties in the form of name-value pairs. See "AppInstGroup".
updateAppInstGroupReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception

deleteAppInstGroupReq

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

Table 6-10 deleteAppInstGroupReq(appAccountId, appInstGroupId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
deleteAppInstGroupReqReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception

listAppAccounts

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

Table 6-11 listAppAccounts(state)

Parameter Name	Type	Description
state	tns1:State	Input parameter. Indicates the states on which states to filter the result. "State".
listAppAccountsReturn	Array of xsd:string	Return parameter. A list of IDs of Application Accounts.
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

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 6-12 getAppAccount(appAccountId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
getAppAccountReturn	tns1:AppAccount	Return parameter. A data structure with details about the Application Account. See "AppAccount".
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

getAppAccountState

Retrieves the state of a specific Application Account.

Table 6-13 getAppAccountState(appAccountId

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
getAppAccountStateReturn	tns1:State	Return parameter. Information on the state of the Application Account. See "State"
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

activateAppAccount

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

Table 6-14 activateAppAccount(appAccountId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
activateAppAccountReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception. The Application Account is not in an appropriate state to allow the account to be activated.

deactivateAppAccount

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

Table 6-15 deactivateAppAccount(appAccountId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
deactivateAppAccountReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception. The state of the Application Account does not allow the account to be deactivated.

activateAppInstGroup

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

Table 6-16 activateAppInstGroup(appAccountId, appInstGroupId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
activateAppInstGroupReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception. The Application Instance is not in an appropriate state to allow the account to be activated.

getAppInstGroupState

Gets the state of an Application Instance.

Table 6-17 getAppInstGroupState(appAccountId, appInstGroupId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
getAppInstGroupStateReturn	tns1:State	Return parameter. The state of the Application Instance. See "State".
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

deactivateAppInstGroup

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

Table 6-18 deactivateAppInstGroup(appAccountId, appInstGroupId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
deactivateAppInstGroupReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception. The Application Instance is not in an appropriate state to allow the account to be deactivated.

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 6-19 registerAppInstGroupReq(appAccountId, appInstGroupId, appInstGroup, password)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance to be registered.
appInstGroup	tns1:AppInstGroup	Input parameter. The CRM/PRM application-defined properties in the form of name-value pairs. See "AppInstGroup".
password	xsd:string	Input parameter. The password the application will use when authenticating on Oracle Communications Services Gatekeeper
registerAppInstGroupReqReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception

deactivateAppInstGroup

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

Table 6-20 deactivateAppInstGroup(appAccountId, appInstGroupId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
deactivateAppInstGroupReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception
INVALID_STATE	N/A	Exception. The Application Instance is not in an appropriate state to allow the account to be activated.

listAppInstGroups

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

Table 6-21 listAppInstGroups(appAccountId, state)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
state	tns1:State	Input parameter. Indicates which states to filter the result on. See "State"
listAppInstGroupsReturn	Array of xsd:string	Return parameter. A list of all Service Application Instance IDs matching the given criteria.
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

getAppInstGroup

Retrieves details about a specific Application Instance.

Table 6-22 getAppInstGroup(appAccountId, appInstGroupId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
getAppInstGroupReturn	tns1:AppInstGroup	return parameter. A data structure with details about the Application Instance. See "AppInstGroup".
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

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. This operation takes no input parameters.

Table 6-23 getSpAccountSla()

Parameter Name	Type	Description
getSpAccountSlaReturn	xsd:string	Return parameter. The Service Provider SLA.
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

getSpAccountSlaByType

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

Table 6-24 getSpAccountSlaByType(slaType)

Parameter Name	Type	Description
slaType	xsd:string	Input parameter. 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 Accounts and SLAs Guide.
getSpAccountSlaByType	xsd:string	Return parameter. The SLA.
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

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 6-25 getAppAccountSla(appAccountId)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The Application Account to retrieve the SLA for.
getAppAccountSlaReturn	xsd:string	Return parameter. The application-level SLA.
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

getAppAccountSlaByType

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

Table 6-26 getAppAccountSlaByType(slaType, appAccountId)

Parameter Name	Type	Description
slaType	xsd:string	Input parameter. 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 Accounts and SLAs Guide.
appAccountId	xsd:string	Input parameter. The Application Account to retrieve the SLA for.
getAppAccountSlaReturn	xsd:string	Return parameter. The application-level SLA.
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

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 6-27 setAppInstGroupPassword(appAccountId, appInstGroupId, newPassword)

Parameter Name	Type	Description
appAccountId	xsd:string	Input parameter. The ID of the Application Account.
appInstGroupId	xsd:string	Input parameter. The ID of the Application Instance.
newPassword	xsd:string	Input parameter. The new password.
setAppInstGroupPasswordReturn	void	Return parameter
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

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 6-28 changeSpAccountPassword(oldPassword, newPassword

Parameter Name	Type	Description
oldPassword	xsd:string	Input parameter. The current password.
newPassword	xsd:string	Input parameter. The new password.
changeSpAccountPasswordReturn	void	Return parameter.
ACCESS_DENIED	N/A	Exception
CommonException	N/A	Exception

Exceptions

These exceptions are thrown by this interface.

ACCESS_DENIED

Exceptions of this type are raised when the operation is not permitted. 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

These are data types used by this interface.

AppAccount

Description of an Application Account.

Table 6-29 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 6-30 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 6-31 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 6-32 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.

See"Account States" for more information about states, and transitions between different states.

Table 6-33 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	N/A	No traffic is allowed through the Oracle Communications Services Gatekeeper when the account or group is in this state.
UPDATE_PENDING	N/A	There is a pending update request. The request must be responded to by the Operator.
DELETE_PENDING	N/A	There is a pending delete request on the account or group. The request must be responded to by the Operator
LOCKED	N/A	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.