posactivate tech spec
TRANSCRIPT
-
7/27/2019 POSActivate Tech Spec
1/22
-
7/27/2019 POSActivate Tech Spec
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
-
7/27/2019 POSActivate Tech Spec
3/22
Pos Activate Specification Document Page 3 of 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
-
7/27/2019 POSActivate Tech Spec
4/22
Pos Activate Specification Document Page 4 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 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
-
7/27/2019 POSActivate Tech Spec
5/22
-
7/27/2019 POSActivate Tech Spec
6/22
Pos Activate Specification Document Page 6 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 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/27/2019 POSActivate Tech Spec
7/22
Pos Activate Specification Document Page 7 of 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
-
7/27/2019 POSActivate Tech Spec
8/22
Pos Activate Specification Document Page 8 of 22
psnIdentifier
Element Data Type Description Validation Notes
Psn ProductSerialNumber .
partnerPSN PartnerProductSerialNumber
RequestInforequestInfo is used to track requests including duplicates.
Element Data Type Description Validation Notes
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.
-
7/27/2019 POSActivate Tech Spec
9/22
Pos Activate Specification Document Page 9 of 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 -
7/27/2019 POSActivate Tech Spec
10/22
Pos Activate Specification Document Page 10 of 22
??
-
7/27/2019 POSActivate Tech Spec
11/22
Pos Activate Specification Document Page 11 of 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
-
7/27/2019 POSActivate Tech Spec
12/22
Pos Activate Specification Document Page 12 of 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 -
7/27/2019 POSActivate Tech Spec
13/22
Pos Activate Specification Document Page 13 of 22
4 Design
-
7/27/2019 POSActivate Tech Spec
14/22
Pos Activate Specification Document Page 14 of 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
-
7/27/2019 POSActivate Tech Spec
15/22
Pos Activate Specification Document Page 15 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 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 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 INCOMMo 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
-
7/27/2019 POSActivate Tech Spec
16/22
Pos Activate Specification Document Page 16 of 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
-
7/27/2019 POSActivate Tech Spec
17/22
Pos Activate Specification Document Page 17 of 22
-
7/27/2019 POSActivate Tech Spec
18/22
Pos Activate Specification Document Page 18 of 22
8 Sequence Diagram
-
7/27/2019 POSActivate Tech Spec
19/22
Pos Activate Specification Document Page 19 of 22
9 Common Flows
-
7/27/2019 POSActivate Tech Spec
20/22
Pos Activate Specification Document Page 20 of 22
10 Use Cases
-
7/27/2019 POSActivate Tech Spec
21/22
Pos Activate Specification Document Page 21 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 SUCCESS
0001 ERROR
0004 INTERNAL_ERROR
0005 VALIDATION_ERROR
-
7/27/2019 POSActivate Tech Spec
22/22
Pos Activate Specification Document Page 22 of 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