# Integration Guidelines for Partner Relationship Management

# 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.