posactivate tech spec

7/27/2019 POSActivate Tech Spec

1/22


2/22

Pos Activate Specification Document Page 2 of 22

1 Change History

Date Version Release Owner Description

11-Feb-2012 1.0 Ragini Bajpai Added details for posActivate API


3/22


2 Table of Contents

1 Change History ................................................................................................................................................................................................................................ 22 Table of Contents ............................................................................................................................................................................................................................. 33 Introduction ...................................................................................................................................................................................................................................... 4

3.1 Purpose ..................................................................................................................................................................................................................................... 43.2 Scope......................................................................................................................................................................................................................................... 43.3 Definitions, Acronyms and Abbreviations .................................................................................................................................................................................. 43.4 References ................................................................................................................................................................................................................................ 43.4.1 Documents .................................................................................................................................................................................................................................. 43.4.2 EBE 1.0 Understanding .............................................................................................................................................................................................................. 53.5 Overview .................................................................................................................................................................................................................................... 6

3.5.1 Request Structure .............................................................................................................................................................................................................. 73.5.1.1 Sample Request ......................................................................................................................................................................................................... 9

3.5.2 Response Structure ......................................................................................................................................................................................................... 113.5.2.1 Sample Response ..................................................................................................................................................................................................... 12

4 Design ............................................................................................................................................................................................................................................ 135 API Flow ......................................................................................................................................................................................................................................... 14

5.1 Protocol Layer ......................................................................................................................................................................................................................... 145.2 Application Layer ..................................................................................................................................................................................................................... 145.3 Service Layer ........................................................................................................................................................................................................................... 15

6 Database Operations: .................................................................................................................................................................................................................... 167 Class Diagram ................................................................................................................................................................................................................................ 168 Sequence Diagram ........................................................................................................................................................................................................................ 189 Common Flows .............................................................................................................................................................................................................................. 1910 Use Cases ................................................................................................................................................................................................................................... 2011 Key Response Values ................................................................................................................................................................................................................. 2112 Detailed Status ............................................................................................................................................................................................................................ 22


4/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 providersas well.

3.2 Scope

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

3.3 Definitions, Acronyms and Abbreviations

Item Description

POS Point Of Sale

3.4 References

3.4.1 Documents

Document Version Date

//depot/Consumer_Online_Services/Core_API/olp_core/trunk/docs/APIs/PosaService/PosActivate_Interface_Spec.docx

1.0

Staples POSA - High Level Solution Overview 3.0


5/22


6/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 activatedThen 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.


7/22


3.5.1 Request Structure

PosActivateRequest extends ColpBaseRequest

Element Data Type Description Validation Notes

requestVendor VendorInfo Vendor credentials. Not null, and caller must have access. Usingexistingvalidation

Version Int Optional attribute used in COLP

requestInfo RequestInfo Unique request ID and resendinformation.

Not null. Usingexistingvalidation

psnIdentifier PSNIdentifier It contains 2 choice elementspsn/partnerPSN

integrationProvider Enum It contains 3 values :EPay

BLACKHAWKINCOMM


8/22


psnIdentifier


Psn ProductSerialNumber .

partnerPSN PartnerProductSerialNumber

RequestInforequestInfo is used to track requests including duplicates.


requestID String String used toidentify requests.

Not blank (Category 1, Status - 0005,DetailedStatus 0507, Message -EMPTY_REQUEST_ID).String can contain up to 50 alpha numericcharacters. (Category 1, Status - 0005,DetailedStatus 0508 Message-INVALID_REQUEST_ID_LENGTH).

requestID must be unique for each successfulrequest. If a request has to be retried, samerequestID can be used but resend parameter shouldbe incremented by one. If a requestID is reused butresend is not incremented, duplicate request errorcode will be returned.

Resend Integer Request count incase of retry.

Not null. resend cannot be less than zero.This parameterneeds to be incremented by one in case of a requestretry.

VendorInfo

Element DataType

Description Validation Notes

vendorID Int Vendor Id should be greater than zero and must exist.

vendorPW String Vendor Password should be valid

vendorSiteIDint Vendor Site Id should be greater than zero and must

exist.

clientSystemID String Optional.

endUserID String Optional.

endUserType String Optional.


9/22


3.5.1.1 Sample Request

?????

??EPAY?

??

?
https://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fschemas.xmlsoap.org%2fsoap%2fenvelope%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fschemas.xmlsoap.org%2fsoap%2fenvelope%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fschemas.xmlsoap.org%2fsoap%2fenvelope%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fps.webservices.symantec.com%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fps.webservices.symantec.com%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fps.webservices.symantec.com%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fps.webservices.symantec.com%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fschemas.xmlsoap.org%2fsoap%2fenvelope%2f


10/22


??


11/22


3.5.2 Response Structure

PosActivateResponse extends ColpBaseResponse

Element Data Type Description

posPartnerStatus String Status expected by the partner

Result Result COLP resultserverTimestamp Date Server time.

Attributes NameValuePairList

Result

Element Data Type Description Notes

category String Category can be 0,1

status String

detailedStatusList List Contains 1 or more detailStatus

detailedStatus String

statusMessage String


12/22


3.5.2.1 Sample Response

??

?

??

??

?
https://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fschemas.xmlsoap.org%2fsoap%2fenvelope%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fps.webservices.symantec.com%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fps.webservices.symantec.com%2fhttps://mail.hcl.com/owa/redir.aspx?C=tzZffFF28UqD1t_ON3WEDC9MwtEP3M8I7MIXicgCHr2C6gcyusCTc7iKBKDcTNsrj9EwK4CuIxw.&URL=http%3a%2f%2fschemas.xmlsoap.org%2fsoap%2fenvelope%2f


13/22


4 Design


14/22


5 API Flow

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

Protocol

Application

Service

Domain5.1 Protocol Layer

Protocol layer contains Request and Response objects of the API. This layer is responsible to convert protocol objects to domain objects and placecall 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/partnerPSNirrespective of integration provider?)

If integration Provider is BLACKHAWK 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.

If integration Provider is INCOMM then psn identifier should be present in request. otherwise return status-0005. DetailedStatus-0556 andstatus 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-0556and status Message INVALID_PID_FOR_PARTNER will be returned in response.

5.2 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 anddomain).

Verify request Vendor, if vendorId and password does not match with DB then ACCESS_DENIED message with detailedStatus- 0150 will bereturned in response

Place call to service layer


15/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 inresponse.

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 BLACKHAWKo Execute rules defined in bh_posActivateRules.xlso Update status of product


Update enable state of subscription_current to enabled

Update status of subscription_current to paid.(Need confirmation)

If integration provider is INCOMMo Execute rules defined in incomm_posActivateRules.xls

o Update status of product


Update enable state of subscription_current to enabled

Update status of subscription_current to paid.(Need Confirmation)

Return status, detailedStatus, posStatus in response


16/22


6 Database Operations:

S. No. Table Name Operation Change

1. EBE_CODES Write Inserted API details in EBE_CODES table before API execution

2 POPCON Read/Update Update status column

3. POPCON_CURRENT Read

4. SUBSCRIPTION_CU

RRENT

Read/Update Update enable state column

5 EBE_SUB_TRANSAC

TION

Read/Insert Create new record for request Id provided in request

7 Class Diagram


17/22



18/22


8 Sequence Diagram


19/22


9 Common Flows


20/22


10 Use Cases


21/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 SUCCESS

0001 ERROR

0004 INTERNAL_ERROR

0005 VALIDATION_ERROR


22/22


12 Detailed Status

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

Detailed

Status

Code

Category Status posStatus

(BLACKHAWK)

posStatus

(Incomm)

Definition

- 0000 00 0000 Success: Activation of Product succeeded- 1 12290 21 10030 Product was already activated- 1 12291 TBD TBD Product was found to be disabled - 1 12292 04 TBD Product was found to be disabled for refund- 1 12293 43 10083 Product was found to be disabled for fraud- 1

1229507 TBD Product was found to be cancelled for an indeterminate

reason- 1

1229604 10038

Product was found to be in use already (redeemed)

- 1 0100 TBD TBD Invalid vendor

- 1 0150 TBD TBD API access denied for vendor

- 1 21550 TBD TBD Invalid clientSystemID

- 1 20000 TBD TBD Partner PSN: null

- 1 9102 TBD TBD Partner PSN: was not found

- 1 21500 TBD TBD Rule execution failure: General exception

- 1 21501 TBD TBD Rule execution failure: No rules executed

- 1 21502 TBD TBD Rule execution failure: Multiple rules executed

- 0001 TBD TBD Unhandled exception

0556 1 0005 TBD TBD Invalid PID for partner