1、 ETSI TR 102 397-7 V1.1.1 (2005-08)Technical Report Open Service Access (OSA);Mapping of Parlay X Web Services to Parlay/OSA APIs;Part 7: Account Management MappingETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 2 Reference DTR/TISPAN-01021-07-OSA Keywords API, OSA, service ETSI 650 Route des Lucioles F-069
2、21 Sophia Antipolis Cedex - FRANCE Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16 Siret N 348 623 562 00017 - NAF 742 C Association but non lucratif enregistre la Sous-Prfecture de Grasse (06) N 7803/88 Important notice Individual copies of the present document can be downloaded from: http:/www.etsi
3、.org The present document may be made available in more than one electronic version or in print. In any case of existing or perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF). In case of dispute, the reference shall be the printing on
4、ETSI printers of the PDF version kept on a specific network drive within ETSI Secretariat. Users of the present document should be aware that the document may be subject to revision or change of status. Information on the current status of this and other ETSI documents is available at http:/portal.e
5、tsi.org/tb/status/status.asp If you find errors in the present document, please send your comment to one of the following services: http:/portal.etsi.org/chaircor/ETSI_support.asp Copyright Notification No part may be reproduced except as authorized by written permission. The copyright and the foreg
6、oing restriction extend to reproduction in all media. European Telecommunications Standards Institute 2005. The Parlay Group 2005. All rights reserved. DECTTM, PLUGTESTSTM and UMTSTM are Trade Marks of ETSI registered for the benefit of its Members. TIPHONTMand the TIPHON logo are Trade Marks curren
7、tly being registered by ETSI for the benefit of its Members. 3GPPTM is a Trade Mark of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners. ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 3 Contents Intellectual Property Rights5 Foreword.5 1 Scope 6 2 References 6 3 Defini
8、tions and abbreviations.6 3.1 Definitions6 3.2 Abbreviations .6 4 Mapping description.6 5 Sequence diagrams.7 5.1 Query account balance .7 5.2 Retrieve account transaction history.7 5.3 Query account credit expiry date (Parlay 5.0 only)8 5.4 Increment account balance (Parlay 5.0 only) .8 5.5 Increme
9、nt account balance using Voucher (Parlay 5.0 only) .9 6 Detailed mapping information9 6.1 Operations 9 6.1.1 getBalance.9 6.1.1.1 Mapping to IpAccountManager.queryBalanceReq.9 6.1.1.2 Mapping from IpAppAccountManager.queryBalanceRes.10 6.1.1.3 Mapping from IpAppAccountManager.queryBalanceErr.10 6.1.
10、2 getHistory .10 6.1.2.1 Mapping to IpAccountManager.retrieveTransactionHistoryReq11 6.1.2.2 Mapping from IpAppAccountManager.retrieveTransactionHistoryRes11 6.1.2.3 Mapping from IpAppAccountManager.retrieveTransactionHistoryErr11 6.1.3 getCreditExpiryDate (Parlay 5.0 only) .11 6.1.3.1 Mapping to Ip
11、AccountManager.queryBalanceExpiryDateReq.12 6.1.3.2 Mapping from IpAppAccountManager.queryBalanceExpiryDateRes.12 6.1.3.3 Mapping from IpAppAccountManager.queryBalanceExpiryDateErr.12 6.1.4 balanceUpdate (Parlay 5.0 only).12 6.1.4.1 Mapping to IpAccountManager.updateBalanceReq.13 6.1.4.2 Mapping fro
12、m IpAppAccountManager.updateBalanceRes.13 6.1.4.3 Mapping from IpAppAccountManager.updateBalanceErr.13 6.1.5 voucherUpdate (Parlay 5.0 only) 13 6.1.5.1 Mapping to IpAccountManager.queryUserVouchersReq.14 6.1.5.2 Mapping from IpAppAccountManager.queryUserVouchersRes.14 6.1.5.3 Mapping from IpAppAccou
13、ntManager.queryUserVouchersErr.14 6.1.5.4 Mapping to IpAccountManager.queryVoucherReq.14 6.1.5.5 Mapping from IpAppAccountManager.queryVoucherRes.15 6.1.5.6 Mapping from IpAppAccountManager.queryVoucherErr.15 6.1.5.7 Mapping to IpAccountManager.updateBalanceReq.15 6.1.5.8 Mapping from IpAppAccountMa
14、nager.updateBalanceRes.15 6.1.5.9 Mapping from IpAppAccountManager.updateBalanceErr.15 6.1.5.10 Mapping to IpAccountManager.destroyVoucherReq16 6.1.5.11 Unmapped Elements .16 6.2 Exceptions 16 6.2.1 Mapping from TpBalanceQueryError.16 6.2.2 Mapping from TpTransactionHistoryStatus16 6.2.3 Mapping fro
15、m TpVoucherError.16 6.2.4 Mapping from Parlay/OSA method exceptions 17 ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 4 7 Additional notes .17 History 18 ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 5 Intellectual Property Rights IPRs essential or potentially essential to the present document may have been decl
16、ared to ETSI. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: “Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards“, which
17、 is available from the ETSI Secretariat. Latest updates are available on the ETSI Web server (http:/webapp.etsi.org/IPR/home.asp). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not
18、referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document. Foreword This Technical Report (TR) has been produced by ETSI Technical Committee Telecommunications and Internet converged Services and Protocols for Advance
19、d Networking (TISPAN). The present document is part 7 of a multi-part deliverable covering Open Service Access (OSA); Mapping of Parlay X Web Services to Parlay/OSA APIs, as identified below: Part 1: “Common Mapping“; Part 2: “Third Party Call Mapping“; Part 3: “Call Notification Mapping“; Part 4: “
20、Short Messaging Mapping“; Part 5: “Multimedia Messaging Mapping“; Part 6: “Payment Mapping“; Part 7: “Account Management Mapping“; Part 8: “Terminal Status Mapping“; Part 9: “Terminal Location Mapping“; Part 10: “Call Handling Mapping“; Part 11: “Audio Call Mapping“; Part 12: “Multimedia Conference
21、Mapping“; Part 14: “Presence Mapping“; NOTE: Part 13 has not been provided as there is currently no defined mapping between ES 202 391-13 4 and the Parlay/OSA APIs. If a mapping is developed, it will become part 13 of this series. The present document has been defined jointly between ETSI, The Parla
22、y Group (http:/www.parlay.org) and the 3GPP. ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 6 1 Scope The present document specifies the mapping of the Parlay X Account Management Web Service to the Account Management Service Capability Feature (SCF). The Parlay X Web Services provide powerful yet simple,
23、highly abstracted, imaginative, telecommunications functions that application developers and the IT community can both quickly comprehend and use to generate new, innovative applications. The Open Service Access (OSA) specifications define an architecture that enables application developers to make
24、use of network functionality through an open standardized interface, i.e. the Parlay/OSA APIs. 2 References For the purposes of this Technical Report (TR), the following references apply: 1 ETSI TR 121 905: “Universal Mobile Telecommunications System (UMTS); Vocabulary for 3GPP Specifications (3GPP
25、TR 21.905)“. 2 W3C Recommendation (2 May 2001): “XML Schema Part 2: Datatypes“. NOTE: Available at http:/www.w3.org/TR/2001/REC-xmlschema-2-20010502/. 3 ETSI TR 102 397-1: “ Open Service Access (OSA); Mapping of Parlay X Web Services to Parlay/OSA APIs; Part 1: Common Mapping“. 4 ETSI ES 202 391-13:
26、 “Open Service Access (OSA); Parlay X Web Services; Part 13: Address List Management“. 3 Definitions and abbreviations 3.1 Definitions For the purposes of the present document, the terms and definitions given in TR 102 397-1 3 apply. 3.2 Abbreviations For the purposes of the present document, the ab
27、breviations given in TR 102 397-1 3 apply. 4 Mapping description The Account Management capability can be implemented with Parlay/OSA Account Management. It is applicable to ETSI OSA 1.x/2.x/3.x, Parlay/OSA 3.x/4.x/5.x and 3GPP Releases 4 to 6. Some Account Management web service operations cannot b
28、e mapped to Parlay/OSA releases earlier than ETSI 3.x/ Parlay 5.x/ 3GPP 6.x . Where applicable, this constraint is identified in clauses 5 and 6. ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 7 5 Sequence diagrams 5.1 Query account balance Application Account Management IpApp Account Manager IpAccount Man
29、ager getBalanceRequest“new“queryBalanceReq() queryBalanceRes () getBalanceResponse “forward event“ Figure 1 5.2 Retrieve account transaction history Application Account ManagementIpApp AccountManager IpAccountManager getHistoryRequest “new“retrieveTransactionHistoryReq()retrieveTransactionHistoryRes
30、() getHistoryResponse “forward event“Figure 2 ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 8 5.3 Query account credit expiry date (Parlay 5.0 only) Application Account Management IpApp Account Manager IpAccount Manager “new“queryBalanceExpiryDateReq() queryBalanceExpiryDateRes() getCreditExpiryDateReques
31、tgetCreditExpiryDateResponse “forward event“Figure 3 5.4 Increment account balance (Parlay 5.0 only) Application Account Management IpApp Account Manager IpAccount Manager “new“ balanceUpdateRequestbalanceUpdateResponseupdateBalanceReq() updateBalanceRes() “forward event“ Figure 4 ETSI ETSI TR 102 3
32、97-7 V1.1.1 (2005-08) 9 5.5 Increment account balance using Voucher (Parlay 5.0 only) ApplicationAccount Management IpApp AccountManager IpAccountManager “new“ queryUserVouchersReq() OR queryVoucherReq() queryUserVouchersRes() OR queryVoucherRes()voucherUpdateResponsevoucherUpdateRequest updateBalan
33、ceReq() updateBalanceRes() destroyVoucherReq() destroyVoucherRes() “forward event“ “forward event“ “forward event“ Figure 5 6 Detailed mapping information 6.1 Operations 6.1.1 getBalance The sequence diagram in clause 5.1 illustrates the flow for the getBalance operation. The getBalance operation is
34、 synchronous from the Parlay X clients point of view. It is mapped to the following Parlay/OSA methods: IpAccountManager.queryBalanceReq; IpAppAccountManager.queryBalanceRes; IpAppAccountManager.queryBalanceErr. 6.1.1.1 Mapping to IpAccountManager.queryBalanceReq The IpAccountManager.queryBalanceReq
35、 method is invoked with the following parameters. Name Type Comment users TpAddressSet Populated with one TpAddress element, constructed based on the URI provided in the EndUserIdentifier part of getBalance, mapped as described in TR 102 397-1 3. ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 10Note that t
36、here is no direct mapping to Parlay/OSA for the optional EndUserPin part, which contains the end users credentials for authorizing access to the account. However, there is a mandatory series of authentication and access security steps that are performed between the Account Management Web Service and
37、 the Parlay/OSA Framework SCF, for example the Service Agreement Management APIs, that restrict and/or govern access to accounts via the Parlay/OSA Account Management SCF. The credentials supplied to the Parlay X Account Management web service by the Parlay X client (e.g. in the EndUserPin part) may
38、 be mapped indirectly to a security “access profile“ negotiated between the the Account Management web service and the Parlay/OSA Framework and Account Management SCFs. The result from IpAccountManager.queryBalanceReq is used internally to correlate the callbacks: i.e. subsequent invocations of IpAp
39、pAccountManager.queryBalanceRes or IpAppAccountManager.queryBalanceErr. Parlay exceptions thrown by IpAccountManager.queryBalanceReq are mapped to Parlay X exceptions as defined in clause 6.2.4. 6.1.1.2 Mapping from IpAppAccountManager.queryBalanceRes When balance information is available, the IpApp
40、AccountManager.queryBalanceRes callback is invoked. It is expected to contain a single TpBalance element whose UserID field matches the TpAddress passed to the balance request operation. The fields of the TpBalance element are mapped as follows. Name Type Comment UserID TpAddress Matches the TpAddre
41、ss element passed to the balance request operation. StatusCode TpBalanceQueryError If the value is P_BALANCE_QUERY_OK, a result is returned, otherwise an exception is thrown by getBalance using the mapping from TpBalanceQueryError values to Parlay X Exceptions described in clause 6.2.1. BalanceInfo
42、TpBalanceInfo If the StatusCode value (above) is P_ BALANCE_QUERY_OK, then the Amount result returned from getBalance will be derived as discussed in the following table. The following table indicates how Parlay TpBalanceInfo data elements are mapped to the Amount part: Name Type Comment Currency Tp
43、String Not mapped. ValuePartA TpInt32 ValuePartB TpInt32 Exponent TpInt32 The value of the Amount part equals: (ValuePartA 232+ ValuePartB) 10-ExponentAdditionalInfo TpString Not mapped. 6.1.1.3 Mapping from IpAppAccountManager.queryBalanceErr If an error prevents the balance information from being
44、reported, the IpAppAccountManager. queryBalanceErr callback is invoked. If this occurs, an exception will be thrown by getBalance based on the value of the cause parameter. Refer to the TpBalanceQueryError to Parlay X exception mapping in clause 6.2.1 for details. 6.1.2 getHistory The sequence diagr
45、am in clause 5.2 illustrates the flow for the getHistory operation. The getHistory operation is synchronous from the Parlay X clients point of view. It is mapped to the following Parlay/OSA methods: IpAccountManager.retrieveTransactionHistoryReq; IpAppAccountManager.retrieveTransactionHistoryRes; Ip
46、AppAccountManager.retrieveTransactionHistoryErr. ETSI ETSI TR 102 397-7 V1.1.1 (2005-08) 116.1.2.1 Mapping to IpAccountManager.retrieveTransactionHistoryReq The IpAccountManager.retrieveTransactionHistoryReq method is invoked with the following parameters. Name Type Comment user TpAddress The TpAddr
47、ess element is constructed based on the URI provided in the EndUserIdentifier part of getHistory, mapped as described in TR 102 397-1 3. transactionInterval TpTimeInterval The StartTime element is generated from the value of the optional Date part. There is no direct mapping to the StopTime element,
48、 although the value of the optional MaxEntries part may enable the Web Service to derive a coarse estimate for this element of transactionInterval. Note that there is no direct mapping to Parlay/OSA for the optional EndUserPin part, which contains the end users credentials for authorizing access to
49、the account; however an indirect mapping exists as discussed in clause 6.1.1.1. Note also that there is no direct mapping for the optional MaxEntries part. The result from IpAccountManager.retrieveTransactionHistoryReq is used internally to correlate the callbacks: i.e. subsequent invocations of IpAppAccountManager.retrieveTransactionHistoryRes or IpAppAccountManager.retrieveTransactionHistoryErr. Parlay exceptions thrown by IpAccountManager.retrieveTransactionHistoryReq are mapped to Parlay X exceptions as defined in clause 6.2.2. 6.1.2
