COLP Pos Activate API

Design Specification

Confidential

1 Change History
Date
11-Feb-2012

Pos Activate Specification Document

Version
1.0

Release

Owner
Ragini Bajpai

Description
Added details for posActivate API

Page 2 of 22

2 Table of Contents
1

Change History ................................................................................................................................................................................................................................ 2

Table of Contents ............................................................................................................................................................................................................................. 3

Introduction ...................................................................................................................................................................................................................................... 4
3.1

Purpose ..................................................................................................................................................................................................................................... 4

3.2

Scope......................................................................................................................................................................................................................................... 4

3.3

Definitions, Acronyms and Abbreviations .................................................................................................................................................................................. 4

3.4

References ................................................................................................................................................................................................................................ 4

3.4.1 Documents .................................................................................................................................................................................................................................. 4

3.4.2 EBE 1.0 Understanding .............................................................................................................................................................................................................. 5
3.5

Overview .................................................................................................................................................................................................................................... 6

3.5.1

Request Structure .............................................................................................................................................................................................................. 7

3.5.1.1
Sample Request ......................................................................................................................................................................................................... 9
3.5.2
Response Structure ......................................................................................................................................................................................................... 11
4

3.5.2.1
Sample Response ..................................................................................................................................................................................................... 12
Design ............................................................................................................................................................................................................................................ 13

API Flow ......................................................................................................................................................................................................................................... 14

5.1

Protocol Layer ......................................................................................................................................................................................................................... 14

5.2

Application Layer ..................................................................................................................................................................................................................... 14

5.3

Service Layer ........................................................................................................................................................................................................................... 15

Database Operations: .................................................................................................................................................................................................................... 16

Class Diagram................................................................................................................................................................................................................................ 16

Sequence Diagram ........................................................................................................................................................................................................................ 18

Common Flows .............................................................................................................................................................................................................................. 19

10

Use Cases ................................................................................................................................................................................................................................... 20

11

Key Response Values ................................................................................................................................................................................................................. 21

12

Detailed Status ............................................................................................................................................................................................................................ 22

Pos Activate Specification Document

Page 3 of 22

3 Introduction
3.1

Purpose
posActivate API provides the ability to activate (unlock) a retail product. This is also referred to as point-of-sale (POS) activation.
Once the product is POS activated, only then can it be activated using the product key.
Earlier this API was created to provide support for Dixons (ePay) partner only. Now it is extended to support BlackHawk and Incomm integration providers
as well.

3.2

Scope

This document covers the design and application flow of posActivate API.

3.3

Definitions, Acronyms and Abbreviations

Item
POS

3.4

Description
Point Of Sale

References
3.4.1 Documents
Document

Version

//depot/Consumer_Online_Services/Core_API/olp_core/trunk/docs/
APIs/PosaService/PosActivate_Interface_Spec.docx
Staples POSA - High Level Solution Overview

1.0

Pos Activate Specification Document

Page 4 of 22

3.0

Date

3.4.2 EBE 1.0 Understanding

Following is the working mechanism for the posActivate in Legacy System:

Create PosaPurchaseResponse with initial Status set to SUCCESS.

Perform validation on input parameters of the PosaPurchaseRequest.
If there is validation any error set the error in response and returns the response.
Checking for DuplicateRequest by querying WBR_TRX_AUDIT table and fetching the record based on apicode, vendorID, siteID and
requestId. If record found then DUPLICATE_REQUEST is set in status.
Based on the Actions Id corresponding method is called where SAS call is made to get the required response from SAS System.
In this case the SAS api that gets called is PosActivate.
SasServicePosActivateRequest is constructed by fetching the required parameters from PosaPurchaseRequest.
Retrieves List of LicenseServers where EB data will be present and call is made to these different servers to process the request made.
Validate SasServicePosActivateRequest and license Servers. If validation fails the throw IllegalArgumentException.
Create SAS Request URL corresponding to posActivate and call is made to corresponding SAS Legacy Environment.
Response received is parsed and SasResponse is constructed.
If response status is success then add entitlement to entitlement list and set status of entitlement to status received in sas response
Else create an empty entitlement and set the status in entitlement and return the Entitlement object.
If entitlements Status is 0 and entitlements subscription is empty the return response with status set to
XLOK_ERROR_GETTING_SUBSCRIPTION.
If there is status set in entitlement other than SUCCESS then corresponding EBE1.0 mapping is made with respect to error returned in
SAS Response and statuses are set in PosaPurchaseResponse.
PosaPurchaseResponse is returned to EBE PT.

Pos Activate Specification Document

Page 5 of 22

3.5

Overview
posActivate API is called by BlackHawk, Incomm and Dixons partners.
The basic flow of API in COLP is described below:

Perform authentication/authorization for vendor details provided in request.

Perform validation on input parameters of the request xml.
Fetch product for provided psn/partnerPSN in response.
If product is not found then throw ProductNotFoundException.
Otherwise if existing status of product is POS_PENDING and product is not already activated
Then update status of product to enabled.
Otherwise send respective status code (calculated based on rules sheet for each partner)
Return status, detailed status and posStatus in response.

Pos Activate Specification Document

Page 6 of 22

3.5.1 Request Structure

PosActivateRequest extends ColpBaseRequest
Element
requestVendor

Data Type
VendorInfo

Description
Vendor credentials.

Validation
Not null, and caller must have access.

Notes
Using
existing
validation

Version
requestInfo

Int
RequestInfo

Optional attribute used in COLP

Unique request ID and resend
information.

Not null.

Using
existing
validation

psnIdentifier

PSNIdentifier

integrationProvider

Enum

It contains 2 choice elements

psn/partnerPSN
It contains 3 values :
EPay
BLACKHAWK
INCOMM

Pos Activate Specification Document

Page 7 of 22

psnIdentifier
Element
Psn
partnerPSN

Data Type
ProductSerialNumber
PartnerProductSerialNumber

Description

Validation
.

Notes

RequestInfo
requestInfo is used to track requests including duplicates.
Element
requestID

Data Type
String

Description
String used to
identify requests.

Resend

Integer

Request count in
case of retry.

Validation
Not blank (Category 1, Status - 0005,
DetailedStatus 0507, Message EMPTY_REQUEST_ID).
String can contain up to 50 alpha numeric
characters. (Category 1, Status - 0005,
DetailedStatus 0508 MessageINVALID_REQUEST_ID_LENGTH).
Not null.

Notes
requestID must be unique for each successful
request. If a request has to be retried, same
requestID can be used but resend parameter should
be incremented by one. If a requestID is reused but
resend is not incremented, duplicate request error
code will be returned.
resend cannot be less than zero.This parameter
needs to be incremented by one in case of a request
retry.

VendorInfo
Element
vendorID
vendorPW

Data
Type
Int
String
int

Description

Validation

vendorSiteID
clientSystemID

String

Vendor Id should be greater than zero and must exist.

Vendor Password should be valid
Vendor Site Id should be greater than zero and must
exist.
Optional.

endUserID
endUserType

String
String

Optional.
Optional.

Pos Activate Specification Document

Page 8 of 22

Notes

3.5.1.1

Sample Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ps="http://ps.webservices.symantec.com/">
<soapenv:Header/>
<soapenv:Body>
<ps:posActivate>
<!--Optional:-->
<posActivateRequest>
<requestInfo><resend/></requestInfo><requestVendor>
<vendorID>?</vendorID>
<vendorPW>?</vendorPW>
<vendorSiteID>?</vendorSiteID>
<!--Optional:-->
<clientSystemID>?</clientSystemID>
<!--Optional:-->
<endUserID>?</endUserID>
<!--Optional:-->
<endUserType>?</endUserType>
</requestVendor>
<!--Optional:-->
<version>?</version>
<integrationProvider>EPAY</integrationProvider>
<action>?</action>
<psnIdentifier>
<!--You have a CHOICE of the next 2 items at this level-->
<partnerPSN>
<partnerProductSerialNumber>?</partnerProductSerialNumber>
</partnerPSN>
<psn>
<productSerialNumber>?</productSerialNumber>
</psn>
</psnIdentifier>
<!--Optional:-->
<transactionTime>?</transactionTime>
<!--Optional:-->
<partnerSpecificDetails>
<!--1 or more repetitions:-->

Pos Activate Specification Document

Page 9 of 22

<nameValuePair>
<name>?</name>
<value>?</value>
</nameValuePair>
</partnerSpecificDetails>
</posActivateRequest>
</ps:posActivate>
</soapenv:Body>
</soapenv:Envelope>

Pos Activate Specification Document

Page 10 of 22

3.5.2 Response Structure

PosActivateResponse extends ColpBaseResponse
Element
posPartnerStatus
Result
serverTimestamp
Attributes

Data Type
String
Result
Date
NameValuePairList

Description
Status expected by the partner
COLP result
Server time.

Result
Element
category
status
detailedStatusList
detailedStatus
statusMessage

Pos Activate Specification Document

Data Type
String
String
List
String
String

Description
Category can be 0,1
Contains 1 or more detailStatus

Page 11 of 22

Notes

3.5.2.1

Sample Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ps="http://ps.webservices.symantec.com/">
<soapenv:Header/>
<soapenv:Body>
<ps:posActivateResponse>
<!--Optional:-->
<return>
<!--Optional:-->
<result>
<category>?</category>
<status>?</status>
<!--Optional:-->
<detailedStatusList>
<!--Zero or more repetitions:-->
<detailedStatus>?</detailedStatus>
</detailedStatusList>
<!--Optional:-->
<statusMessage>?</statusMessage>
</result>
<!--Optional:-->
<serverTimestamp>?</serverTimestamp>
<!--Optional:-->
<attributes>
<!--1 or more repetitions:-->
<nameValuePair>
<name>?</name>
<value>?</value>
</nameValuePair>
</attributes>
<posPartnerStatus>?</posPartnerStatus>
</return>
</ps:posActivateResponse>
</soapenv:Body>
</soapenv:Envelope>

Pos Activate Specification Document

Page 12 of 22

4 Design

Pos Activate Specification Document

Page 13 of 22

5 API Flow
To implement posActivate API, code has been categorized (as per COLP architecture) in following 4 layers:

5.1

Protocol
Application
Service
Domain

Protocol Layer
Protocol layer contains Request and Response objects of the API. This layer is responsible to convert protocol objects to domain objects and place
call to application layer for fulfilment of request.
Below validations are performed at this layer: (Need confirmation do we really need this validation or API will provide support for both psn/partnerPSN
irrespective of integration provider?)

5.2

If integration Provider is BLACKHAWK then partnerPSN identifier should be present in request otherwise return status-0005. DetailedStatus0556 and status Message INVALID_PID_FOR_PARTNER will be returned in response.
If integration Provider is INCOMM then psn identifier should be present in request. otherwise return status-0005. DetailedStatus-0556 and
status Message INVALID_PID_FOR_PARTNER will be returned in response.
If integration Provider is EPAY then partnerPSN identifier should be present in request. otherwise return status-0005. DetailedStatus-0556
and status Message INVALID_PID_FOR_PARTNER will be returned in response.

Application Layer
This layer has following features:

Initiate logging for API

Handle all the exceptions (children Exception of ColpException, ColpValidationException and Exception) thrown at down layers (service and
domain).
Verify request Vendor, if vendorId and password does not match with DB then ACCESS_DENIED message with detailedStatus- 0150 will be
returned in response
Place call to service layer

Pos Activate Specification Document

Page 14 of 22

5.3

Service Layer

This layer is responsible to implement the business logic behind the API. It also communicates with the domain layer to interact with the database.
Service layer supports features to load partner rule sheets, execute rules defined in XLS sheet and update status of Popcon to enabled and enableState of
Subscription_Current to enabled in DB.
Following are the steps performed on service layer on the basis of integration Provider provided in request:

Fetch product for psn/partnerPSN provided in request

If product was not found then throw ProdcutNotFoundException and status- 2048 and Message INVALID_PRODUCT will be returned in
response.
Otherwise Identify integration provider
If integration provider is EPAY :
o Execute all rules defined in epay_posActivateRules.xls
o Update status of product
Update status column of popcon to enable
Update enable state of subscription_current to enabled.
If integration provider is BLACKHAWK
o Execute rules defined in bh_posActivateRules.xls
o Update status of product
Update status column of popcon to enable
Update enable state of subscription_current to enabled
Update status of subscription_current to paid.(Need confirmation)

If integration provider is INCOMM

o Execute rules defined in incomm_posActivateRules.xls
o Update status of product
Update status column of popcon to enable
Update enable state of subscription_current to enabled
Update status of subscription_current to paid.(Need Confirmation)

Return status, detailedStatus, posStatus in response

Pos Activate Specification Document

Page 15 of 22

6 Database Operations:
S. No.
1.

Table Name
EBE_CODES

Operation
Write

Change
Inserted API details in EBE_CODES table before API execution

2
3.
4.

POPCON
POPCON_CURRENT
SUBSCRIPTION_CU
RRENT
EBE_SUB_TRANSAC
TION

Read/Update
Read
Read/Update

Update status column

Read/Insert

Create new record for request Id provided in request

Update enable state column

7 Class Diagram
Pos Activate Specification Document

Page 16 of 22

Pos Activate Specification Document

Page 17 of 22

8 Sequence Diagram

Pos Activate Specification Document

Page 18 of 22

9 Common Flows

Pos Activate Specification Document

Page 19 of 22

10 Use Cases

Pos Activate Specification Document

Page 20 of 22

11 Key Response Values

Following are some of primary return codes that these APIs can return.
If the API succeeded a return code of 0000 success will be returned. Otherwise a non 0000 return code will be returned.
Refer to the status_codes.xls spread sheet for a complete list of return codes for this API.

Code

Definition

0000
0001
0004
0005

SUCCESS
ERROR
INTERNAL_ERROR
VALIDATION_ERROR

Pos Activate Specification Document

Page 21 of 22

12 Detailed Status
Following are some of detailed return codes that this API will return:

Detailed
Status
Code
-

Category

posStatus
(BLACKHAWK)

posStatus
(Incomm)

Definition

0000

00

0000

Success: Activation of Product succeeded

12290

21

10030

Product was already activated

12291

TBD

TBD

Product was found to be disabled

12292

04

TBD

Product was found to be disabled for refund

12293

43

10083

Product was found to be disabled for fraud

07

TBD

12296

04

10038

Product was found to be cancelled for an indeterminate

reason
Product was found to be in use already (redeemed)

0100

TBD

TBD

Invalid vendor

0150

TBD

TBD

API access denied for vendor

21550

TBD

TBD

Invalid clientSystemID

20000

TBD

TBD

Partner PSN: null

9102

TBD

TBD

Partner PSN: was not found

21500

TBD

TBD

Rule execution failure: General exception

21501

TBD

TBD

Rule execution failure: No rules executed

21502

TBD

TBD

Rule execution failure: Multiple rules executed

0001

TBD

TBD

Unhandled exception

0005

TBD

TBD

Invalid PID for partner

0556

Pos Activate Specification Document

Status

12295

Page 22 of 22