Integration Guidelines for Partner Relationship Management

Operator Service

Web Service

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

Interface: OpService

The endpoint for this interface is: http://<host>:<port>/prm_op/services/OpService

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

listAppGroups

Lists all Application Groups

Table 11-1 listAppGroups()

Parameter Name

Type

Description

Input

no input parameters

Returns

Array of xsd:string

A list of all Application Group IDs.

Possible Exceptions

ACCESS_DENIED

CommonException

getAppGroup

Retrieves details about a specific Application Group.

Table 11-2 getAppGroup(appGroupId)

Parameter Name

Type

Description

Input

appGroupId

xsd:string

The ID of the group.

Returns

tns1:AppGroup

Data structure with details about the Application Group. See AppGroup.

Possible Exceptions

ACCESS_DENIED

CommonException

createAppGroup

The new mechanism (createAppGroupByType) for creating application groups adds a parameter, slaType. Groups created using createAppGroup automatically have the slaType hardcoded to the value application.

createSpGroup

The new mechanism (createSpGroupByType) for creating service provider groups adds a parameter, slaType. Groups created using createSpGroup automatically have the slaType hardcoded to the value service_provider.

updateSpGroup

The new mechanism (updateSpGroupByType) for updating service provider groups adds a parameter, slaType. Groups updated using updateSpGroup automatically have the slaType hardcoded to the value service_provider.

Table 11-17 updateSpGroup(spGroupId,spGroup)

Parameter Name

Type

Description

Input

spGroupId

xsd:string

The ID of the group.

spGroup

tns1:SpGroup

The Service Provider-level SLA, and CRM/PRM application-defined properties in the form of name-value pairs. See SpGroup.

Returns

updateSpGroupReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

If group does not exist or if the SLA contains errors, this exception is thrown.

updateSpGroupByType

Updates a Service Provider Group with a new SLA.

Table 11-18 updateSpGroupByType(slaType, spGroupId,spGroup)

Parameter Name

Type

Description

Input

slaType

xsd:String

The SLA type to update.

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.

spGroupId

xsd:string

The ID of the group.

spGroup

tns1:SpGroup

The Service Provider-level SLA, and CRM/PRM application-defined properties in the form of name-value pairs. See SpGroup.

Returns

updateSpGroupByTypeReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

If group does not exist or if the SLA contains errors, this exception is thrown.

listAppInstGroups

Lists all Application Instances for a given combination of Service Provider Account and Application Account. Filtering is possible on the state of the Application Instance

Table 11-19 listAppInstGroups(spAccountId, appAccountId, state)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account. Use null to not filter on this parameter.

appAccountId

xsd:string

The ID of the Application Account. Use null to not filter on this parameter.

registerAppInstGroupReq

Requests registration of an Application Instance for a specific combination of a Service Provider Account and Application Account. When this request has been approved (see registerAppInstGroupRes) the newly registered application has all the credentials necessary to be authenticated on the traffic interfaces of the Oracle Communications Services Gatekeeper.

CRM/PRM application-defined properties in the form of name-value pairs.

password

xsd:string

The password the newly created Application Instance will use when authenticating on the Oracle Communications Services Gatekeeper

Returns

registerAppInstGroupReqReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

deleteAppInstGroupReq

Requests deletion of an Application Instance. The Application Instance must be in state INACTIVE in order for this call to be accepted. The request must be approved before the Application Instance is deleted. This is done using deleteAppInstGroupRes,

If there is an SLA associated with the combination of Service Provider Accounts, Application Account, and Application Instance associated with the group, this exception is thrown.

INVALID_STATE

deleteAppInstGroupRes

Responds to a request for deleting an Application Instance for a specific combination of Service Provider Account and Application Account.

It is possible to approve or disapprove the request. Both cases triggers a state transition for the Application Instance. If approved, the Application Instance is deleted, and the Application Instance can no longer be used to authenticate to send the traffic to Oracle Communications Services Gatekeeper.

Data-structure with the Application Instance SLA and application-defined properties in the form of name-value pairs. See AppInstGroup.

Returns

updateAppInstGroupReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

If group does not exist or if the SLA contains errors, this exception is thrown.

updateAppInstGroupRes

Responds to a request for updating Application Instance for a specific combination of Service Provider Account and Application Account.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Application Instance to state ACTIVE. If approved, the Application Instance is updated with the new information.

registerAppAccountReq

Requests registration for an Application Account for a specific Service Provider Account. When this request has been approved by the Operator (see registerAppAccountRes) the Application Account can be associated with an Application Account Group and an Application Instance.

Data structure with details on 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

registerAppAccountRes

Responds to a request to register an Application Account for a specific Service Provider Account. An Application Account Group is also associated with the Application Account.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Application Account. If approved, the Application Account is transferred into state ACTIVE. If Disapproved, the Application Account is deleted.

updateAppAccountRes

Responds to a request to update an Application Account for a specific Service Provider.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Application Account state to Active. If approved, the Application Account is updated with the new information.

If the status of the Application Account is not in state UPDATE_PENDING, this exception is thrown.

getUpdatePendingAppAccount

Gets details about pending update requests for a specific combination of Service Provider and Application Account. The details includes descriptions and CRM/PRM application-defined properties in the form of name-value pairs. Valid only for Application Accounts in state UPDATE_PENDING.

If the status of the Application Account is not in state UPDATE_PENDING, this exception is thrown.

deleteAppAccountReq

Requests the deletion of an Application Account. In order to be deleted, there must be no Application Instance associated with the combination of Service Provider Account and Application Account. The request must be approved before the Application Account is deleted, which is done using deleteAppAccountRes. The Application Account must be in state INACTIVE in order for this call to be accepted.

Table 11-38 deleteAppAccountReq(spAccountId, appAccountId)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

appAccountId

xsd:string

The ID of the Application Account.

Returns

deleteAppAccountReqReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

INVALID_STATE

deleteAppAccountRes

Responds to a request to delete an Application Account for a specific Service Provider Account. The Application Account must be in state DELETE_PENDING in order for this call to be accepted.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Application Account. If approved, the Application Account is simply deleted. If Disapproved, the Application Account is transferred into state INACTIVE.

Table 11-39 deleteAppAccountRes(spAccountId, appAccountId, response)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

appAccountId

xsd:string

The ID of the Application Account.

Returns

deleteAppAccountResReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

INVALID_STATE

updateAppAccount

Updates an Application Account with new data.

Table 11-40 updateAppAccount(spAccountId, appAccountId, appAccount)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

appAccountId

xsd:string

The ID of the Application Account.

appAccount

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

getAppAccount

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

Table 11-41 getAppAccount(spAccountId, appAccountId)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

appAccountId

xsd:string

The ID of the Application Account.

Returns

getAppAccountReturn

tns1:AppAccount

Data structure with details about the Application Account. See AppAccount.

activateAppAccount

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

Table 11-43 activateAppAccount(spAccs appAccountId)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

appAccountId

xsd:string

The ID of the Application Account.

Returns

activateAppAccountReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

INVALID_STATE

If the state of the Application Account does not 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 11-44 deactivateAppAccount(spAccountId, appAccountId)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

appAccountId

xsd:string

The ID of the Application Account.

Returns

deactivateAppAccountReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

INVALID_STATE

If the Application Account is not in an appropriate state to allow the account to be deactivated, this exception is thrown.

registerAppInstGroupRes

Responds to a request to register an Application Instance for a specific combination of a Service Provider Account and Application Group.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Application Instance. If approved, the Application Instance is transferred into state ACTIVE and the application can authenticate with the traffic interfaces exposed by Oracle Communications Services Gatekeeper. If disapproved, the Application Instance is deleted.

If the state of the Application Instance does not allow the account to be deactivated, this exception is thrown.

registerSpAccountReq

Requests registration for a Service Provider Account. Contact details are supplied in the request, together with CRM/PRM application-defined properties. This request must be approved by the Operator (see registerSpAccountRes,

Table 11-48 registerSpAccountReq(spAccountId, spAccount, password)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The desired ID of the Service Provider Account. The Service Provider will use this ID when authenticating to the PRM-SP Web Services.

spAccount

xsd:string

Data structure with details about the Service Provider Account.

password

xsd:string

The password the Service Provider will use when authenticating to the Service Provider part of the Partner Relationship Management interface.

Returns

registerSpAccountReqReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

INVALID_STATE

listAppAccounts

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

Table 11-49 listAppAccounts(spAccountId, state)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account. Use null to not filter on this parameter

registerSpAccountRes

Responds to a request to register a Service Provider Account.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Service Provider Account. If approved, the Service Provider Account is transferred into state ACTIVE and the Service provider can authenticate with the PRM-SP Web Services. If Disapproved, the Service Provider Account is deleted.

If the status of the Service Provider Account is not in state REGISTERED, this exception is thrown.

deleteSpAccountReq

Requests deletion of a Service Provider Account. In order to be deleted, the Service Provider Account must be state INACTIVE. The request must be approved before the Service Provider Account it is deleted. This is done using deleteSpAccountRes,

Table 11-52 deleteSpAccountReq(spAccountId)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Account.

Returns

deleteSpAccountReqReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

If the status of the Service Provider Account is not in state INACTIVE, this exception is thrown.

INVALID_STATE

deleteSpAccountRes

Responds to a request to delete a Service Provider Account. The Service Provider Account must be in state DELETE_PENDING in order for this call to be accepted.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Service Provider Account. If approved, the Service Provider Account is simply deleted. If disapproved, the Service Provider Account is transferred into state INACTIVE.

If the status of the Service Provider Account is not in state INACTIVE, this exception is thrown.

updateSpAccount

Updates a Service Provider Account with new data.

Table 11-54 updateSpAccount(spAccountId, spAccount)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

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

updateSpAccountRes

Responds to a request to update a Service Provider Account.

It is possible to approve or disapprove the request. Both cases trigger a state transition for the Service Provider Account to state ACTIVE. If approved, the Service Provider Account is updated with the new information.

If the status of the Service Provider Account is not in state INACTIVE, this exception is thrown.

getUpdatePendingSpAccount

Gets details about a specific Service Provider account that is in state UPDATE_PENDING. The details include contact information and CRM/PRM application-defined properties in the form of name-value pairs.

.

Table 11-56 getUpdatePendingSpAccount(spAccountId)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

Returns

getUpdatePendingSpAccountReturn

tns1:SpAccount

Details about contact information and CRM/PRM application-defined properties in the form of name-value pairs. See SpAccount.

Possible Exceptions

ACCESS_DENIED

CommonException

INVALID_STATE

If the Service Provide r Account is not in state UPDTATE_PENDING this exception is thrown.

setSpAccountPassword

Sets the password the Service Provider uses to authenticate to use the Partner Relationship Management Interface exposed by Oracle Communications Services Gatekeeper.

.

Table 11-57 setSpAccountPassword(spAccountId, newPassword)

Parameter Name

Type

Description

Input

spAccountId

xsd:string

The ID of the Service Provider Account.

newPassword

xsd:string

The new password.

Returns

setSpAccountPasswordReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

changeOpAccountPassword

Changes the password the Operator uses to authenticate with the Partner Relationship Management Interface exposed by Oracle Communications Services Gatekeeper. The Operator Account is the one the Operator is currently logged in as.

Table 11-58 changeOpAccountPassword(oldPassword, newPassword)

Parameter Name

Type

Description

Input

oldPassword

xsd:string

The password to be changed.

newPassword

xsd:string

The new password.

Returns

changeOpAccountPasswordReturn

void

Possible Exceptions

ACCESS_DENIED

CommonException

getUserLevel

Retrieves the user level of the currently logged in Operator Account. Different user levels have different privileges, and are authorized to different sets of operations.

Table 11-59 changeOpAccountPassword(oldPassword, newPassword)

Parameter Name

Type

Description

Input

No input parameters.

Returns

getUserLevelReturn

tns1:UserLevel

The user level of the currently logged in Operator Account. See UserLevel.

Possible Exceptions

ACCESS_DENIED

CommonException

Exceptions

ACCESS_DENIED

Exceptions of this type are raised when the operation is not permitted. The user does not have the appropriate privilege level 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.

Property

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

Table 11-65 Property

Element name

Datatype

Description

name

xsd:string

Name of the property, with the value defined in Value. Unique with the array.

UserLevel

Defines the user level of the currently logged in Operator user. Enumeration.

The user level reflects the user levels defined for the operations and maintenance of Oracle Communications Services Gatekeeper. Each operation performed via the Partner Management Interface results in one or more standard OAM operations. The user level of the currently authenticated user must satisfy the user level necessary for each of these operations. If this is not the case, the operation performed through the Partner Management Interface is denied.

Table 11-69 State

Element name

Datatype

Description

UNAUTHORIZED

xsd:string

The currently authenticated in user is not authorized to perform any OAM operations.

READ_ONLY

xsd:string

The currently authenticated user is authorized to perform OAM read- or get- operations.

READ_WRITE

xsd:string

The currently authenticated user is authorized to perform OAM write- or set- operations.

ADMINISTRATOR

xsd:string

The currently authenticated user is authorized to perform administrator OAM operations tasks

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 among different states.

Table 11-70 State

Element name

Datatype

Description

REGISTERED

xsd:string

The account or group is has been registered. The registration request must be responded to by the Service Provider.

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 Service Provider.

DELETE_PENDING

There is a pending delete request on the account or group. The request must be responded to by the Service Provider.

LOCKED

Only valid for an Application Instance. The group can be locked due to too many consecutive failed login attempts from an application.