BMW Group

ISPA – DMS
Generic Interface Contract between the
system ISPA (via ISPA Broker) and DMS

Version: 4.0.8 (LF4)

Date: 09.08.2011
Status: in progress / presented / released
Author: Christoph Piotrowski / VH-332,
Felix Grabmeyer / VH-332,
Arnold vom Ende / Cirquent
Julia Bergsteiner / Cirquent,
Joachim Wehler / Cirquent,
Christian Schmidt / Capgemini,
Jan-Henry Ohlert / VS-632
Rainer Wargitsch / VS-662

File: GIC ISPA - DMS via ISPA Broker V4.0.8.docx

Distribution :
VS-632 Harald Meisinger
VS-631 Helmut Grimm, Horst-Werner Böhmcker, Helmut Lutsch,
Werner Thiel
VS-630 Gernot Poisel
V6-A-3 Thomas Menhart, Bernhard Kellerer
VS-65-DE Martin Scholz
BMW Group Page 2
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Amendment Log

Version Date Authors Changes

1.0 21.02.2006 C. Walter Revision
2.0 13.09.06 C. Walter
2.1 28.09.06 C. Walter
2.2 23.11.2006 A. vom Ende / Softlab Modifications together with XML schemes version 2.2from
version 2.1 to version 2.2 are marked up with a yellow
background.
3.0 10.04.07 C. Piotrowski, A. vom Completely revised for the roll-out of ISPA delivery stage 2.
Ende Changes from delivery stage 1 to 2 are marked yellow.
3.01 10.05.07 A. vom Ende Reference to two already existing technical methods added
(section 6.4, 6.5).
Minor corrections without changes of the scope.
The changes from version 3.0 to 3.01 are marked green.
3.1.0 02.07.07 A. vom Ende Minor corrections, enhancements in schemes and docu-
ment, more precise documentation. Parts clearing flag for
LF4 added.
The changes from version 3.0 to 3.1.0 are marked green.
3.1.1 21.11.07 A. vom Ende Minor corrections and enhancements. See Table 11in
section 8.1. The changes from version 3.1.0 to 3.1.1 are
marked purple.
3.1.2 14.01.08 A. vom Ende Method createOrderBase: Element additionalText added in
the order header shall appear on order prinout. See Table
11 in section 8.1. The changes from are marked turquoise.
3.1.2 13.03.08 A. vom Ende No change in the content. Changes from version 3.1.1 to
version 3.1.2 now marked in turquoise rather than in pur-
ple. Sortlab renamed to Cirquent.
3.3.1 19.3.2010 J. Wehler, Requirements of the system proposal SRP Monitoring
J. Bergsteiner version 1.1 (see [13]) are included for the data elements
job list, part, flat rate unit and package.

3.4.1 11.08.2010 C. Schmidt Job handling, new sync status introduced: Requirements of
the system proposal SRP Monitoring version 1.1 (see [14])
are included for the data elements updateOrderHeader.
Delivery State 4 (LF4) requirements.

3.4.2 13.09.2010 F. Grabmeyer, C. Restructured chapters: Separated process description from

Schmidt technical explanation (by interface method)
3.4.3 07.10.2010 F. Grabmeyer, C. Updates after internal feedback round
Schmidt
4.0.0 08.10.2010 Felix Grabmeyer Incorporated Feedback from Christoph Piotrowski,
added experiences from Incadea IMS interface acceptance
4.0.4 19.10.2010 C. Schmidt Added review workshop comments (18.10.2010).
4.0.5 24.10.2010 Felix Grabmeyer Feedback from the meeting between SRP Monitoring and
DMS: Added note that clarifies that synchronizedStatus
updatedInvoice and resetOrderChangeFlag are not used
as of now. Added new package type ACP.
4.0.6 09.12.2010 Felix Grabmeyer Schema update 04.00.06
04.00.06
4.0.6a 12.05.2011 J.-H. Ohlert Added support for pulsed loading of repair history and
usage of creation date as repair date for Parts Reservation
4.0.7 17.05.2011 Rainer Wargitsch Added clarification on ISPA Synchronizer process, updated
distribution list
4.0.8 09.08.2011 J.-H. Ohlert Replaced DMS-based Pulsed Loading with Synchronizer
based pulsed loading of repair history

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 3
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Table of contents
1 Introduction .................................................................................................................................. 10
1.1 Aim of an interface contract....................................................................................................... 10
1.2 Object of the present document ................................................................................................ 10
1.3 Organization of the document ................................................................................................... 10
1.4 Versioning.................................................................................................................................. 11
2 Overview ....................................................................................................................................... 12
2.1 The service process .................................................................................................................. 12
2.2 The communication concept ..................................................................................................... 15
2.3 XML schemes and instances .................................................................................................... 16
2.3.1 XML schemes ................................................................................................................. 16
2.3.2 Conventions for XML instances ...................................................................................... 18
2.3.3 XML instance samples .................................................................................................... 19
2.3.4 Handling namespaces .................................................................................................... 19
2.3.5 Concurrency in overlapping Webservice requests ......................................................... 19
2.4 Method overview ....................................................................................................................... 20
2.5 Enhancements for ISPA delivery stage 2 (LF2) ........................................................................ 21
2.6 Enhancements for ISPA delivery stage 3 (LF3) ........................................................................ 22
2.7 Enhancements for ISPA delivery stage 4 (LF4) ........................................................................ 22
2.8 System overview ....................................................................................................................... 22
2.8.1 Client systems using the interface .................................................................................. 23
3 Functional Description of Interface Features ........................................................................... 24
3.1 Basic Philosophy ....................................................................................................................... 24
3.2 Introduction: Overview functional features and technical interface methods ............................ 24
3.3 Permissions of method access and workflow continuity ........................................................... 24
3.4 Customer/vehicle identification.................................................................................................. 25
3.4.1 Customer/vehicle data .................................................................................................... 25
3.4.2 Customer data ................................................................................................................ 27
3.4.3 Vehicle data .................................................................................................................... 29
3.4.4 Configuration of customer and vehicle data ................................................................... 31
3.4.5 Search customer/vehicle ................................................................................................ 32
3.4.6 Getting the details of a customer/vehicle data set .......................................................... 34
3.4.7 Add customer/vehicle ..................................................................................................... 35
3.4.8 Change customer/vehicle ............................................................................................... 36
3.5 Work items and parts ................................................................................................................ 38
3.5.1 Work items list................................................................................................................. 38
3.5.2 Local SRPs und FRUs from the DMS ............................................................................ 41
3.5.3 Direct adding of local parts ............................................................................................. 44
3.5.4 Price types and price calculation .................................................................................... 46
3.5.5 Work items and parts with fixed price ............................................................................. 49
3.5.6 Request for price information.......................................................................................... 51
3.5.7 Specify billing arrangements (order split) ....................................................................... 51
3.5.8 Check parts availability ................................................................................................... 53
3.5.9 Parts ordering/reservation: Blocking items in DMS (LF4) .............................................. 55
3.6 Orders........................................................................................................................................ 56
3.6.1 General ........................................................................................................................... 56
3.6.2 Transaction Context and new DMS timestamp updating (LF4) ...................................... 56
3.6.3 Order base ...................................................................................................................... 56
3.6.4 Job number issues (LF3 and LF4) .................................................................................. 58
3.6.5 Order split information .................................................................................................... 59
3.6.6 Structure of the customer statement............................................................................... 60

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 4
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.6.7 Order extension (LF4) ..................................................................................................... 61

3.6.8 General principles of the order base data exchange ...................................................... 62
3.6.9 General process of the order base data exchange ........................................................ 63
3.6.10 Sync Mode 1 – order extension by complete replacement ............................................ 64
3.6.11 Sync Mode 2 – order extension only by addition of new work items, parts and packages65
3.6.12 Sync Mode 3 – DMS order is invoiced ........................................................................... 65
3.6.13 Relevant interface requests ............................................................................................ 65
3.6.14 Values for Order Status (synchronizedStatus) ............................................................... 66
3.6.15 Creating an order ............................................................................................................ 69
3.6.16 Managing the order information within the DMS ............................................................ 71
3.6.17 Display of the order status .............................................................................................. 73
3.6.18 Request for order base detail information ...................................................................... 73
3.6.19 Getting a list of DMS orders............................................................................................ 74
3.6.20 Repair History ................................................................................................................. 75
3.6.21 Updating DMS Order Header (LF3, LF4) ....................................................................... 76
3.6.22 Job Handling ................................................................................................................... 76
3.6.23 Release a DMS Order .................................................................................................... 77
3.6.24 Sync status change from updatedInvoice (LF4) ............................................................. 77
3.7 Qualified workshop statement ................................................................................................... 77
4 Technical Interface ...................................................................................................................... 79
4.1 XML Schemas ........................................................................................................................... 79
4.2 XML Methods ............................................................................................................................ 79
4.2.1 Method scoreDMSgeneric::getSetupValues (LF 4) ............................................. 79
4.2.2 Method scoreDMSgeneric::searchCustomer........................................................ 87
4.2.3 Method scoreDMSgeneric::getCustomerDetails ............................................... 90
4.2.4 Method scoreDMSgeneric::addCustomer .............................................................. 93
4.2.5 Method scoreDMSgeneric::changeCustomer........................................................ 95
4.2.6 Method scoreDMSgeneric::getLocalFlatRateGroupList ................................ 98
4.2.7 Method scoreDMSgeneric::getLocalFlatRateGroup ........................................ 99
4.2.8 Method scoreDMSgeneric::getLocalFlatRateDetails .................................. 101
4.2.9 Method scoreDMSgeneric::getLocalSRPGroupList......................................... 102
4.2.10 Method scoreDMSgeneric::getLocalSRPGroup ................................................. 103
4.2.11 Method scoreDMSgeneric::getLocalSRPDetails ............................................. 104
4.2.12 Method scoreDMSgeneric::getLocalPartDetails ........................................... 106
4.2.13 Method scoreDMSgeneric::getPriceInformation ........................................... 107
4.2.14 Method scoreDMSgeneric::checkPartsAvailability .................................... 113
4.2.15 Method orderDMS::getOrderBase ......................................................................... 116
4.2.16 Method orderDMS::checkOrderBaseStatus ........................................................ 119
4.2.17 Method orderDMS::getOrderList ......................................................................... 121
4.2.18 Method orderDMS::storeNewOrderBase .............................................................. 123
4.2.19 Method orderDMS::updateOrderHeader (LF4) ..................................................... 128
4.2.20 Method orderDMS::releaseOrder (LF4)................................................................ 129
4.2.21 Method orderDMS::resetOrderChangeFlag (LF 4) ............................................. 130
4.2.22 Method orderDMS::addJob (LF3, LF4) .................................................................... 131
4.2.23 Method orderDMS::cancelJob (LF4) ...................................................................... 133
4.2.24 Method orderDMS::printOrderBase (LF4) .......................................................... 135
4.3 XML data types ....................................................................................................................... 136
4.3.1 General ......................................................................................................................... 136
4.3.2 Type scoreDMSgeneric::typeSchemaVersionReference................................ 136
4.3.3 Type scoreGenericTypes::dealerType .............................................................. 137
4.3.4 Type scoreGenericTypes::typeUserInformation .......................................... 138

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 5
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.5 Type scoreGenericTypes::typeVehicleReference ........................................ 139

4.3.6 Type scoreGenericTypes::typeVin .................................................................... 139
4.3.7 Type scoreGenericTypes::typeUnitValue ....................................................... 140
4.3.8 Type scoreGenericTypes::typeMileage ............................................................ 141
4.3.9 Type scoreGenericTypes::typeCustomerResult............................................. 142
4.3.10 Type scoreGenericTypes::typeCustomerDetail............................................. 145
4.3.11 Type scoreDMSgeneric::typeVehicleDetails ................................................. 146
4.3.12 Type scoreDMSgeneric::typeFlatRatePriceRequest .................................... 147
4.3.13 Type scoreDMSgeneric::typePartPriceRequest............................................. 147
4.3.14 Type scoreDMSgeneric::typePartPriceEntry ................................................. 148
4.3.15 Type orderDMS::typeOrderBase (Read/Write) (LF4) .................................... 149
4.3.16 Type orderDMS::typeVehicle ............................................................................... 152
4.3.17 Type orderDMS::typeJob (Read/Write) (LF4) .................................................. 152
4.3.18 Type orderDMS::typeJobList (Read/Write) (LF 4) ........................................ 155
4.3.19 Type orderDMS::typePart (Read/ Write) (LF4)............................................. 155
4.3.20 Typ orderDMS::typeSplitInformation (LF 4) ................................................... 157
4.3.21 Type qualifiedStatement::typeCustomerStatement .................................... 158
4.3.22 Type orderDMS::typeFlateRateUnit(Read/Write) (LF 4).............................. 159
4.3.23 Type orderDMS::typePackage (Read/Write) (LF 4) ........................................ 161
4.3.24 Type scoreGenericTypes::typePackageFlags (LF 4) ...................................... 164
4.4 XML Simple types ................................................................................................................... 164
4.5 XML Element Groups .............................................................................................................. 167
4.5.1 Group groupCustomerCommunication ......................................................................... 168
4.5.2 Group groupCustomerAssigned ................................................................................... 168
4.5.3 Group groupCustomerLocation .................................................................................... 169
4.5.4 Group groupCustomerPerson....................................................................................... 169
4.5.5 Group groupCustomerBackground ............................................................................... 170
4.5.6 Group groupCustomerCategories................................................................................. 171
4.5.7 Group groupVehicleProductionDetails ......................................................................... 172
4.5.8 Group groupVehicleServiceDetails ............................................................................... 173
4.5.9 Group groupOfferPriceEntry ......................................................................................... 174
4.5.10 Group groupPriceEntry ................................................................................................. 175
4.5.11 Group groupOrderHeader............................................................................................. 175
4.5.12 Group groupDiscountedPrice ....................................................................................... 177
4.5.13 Group groupJobrow (order split information) ................................................................ 178
4.5.14 Group groupOrderHeader (LF4) ................................................................................... 179
4.5.15 Group groupOrderSplit ................................................................................................. 180
5 Error handling ............................................................................................................................ 181
5.1 Error structure ......................................................................................................................... 181
5.1.1 Hints .............................................................................................................................. 182
5.2 Error categories ....................................................................................................................... 182
5.3 Error codes .............................................................................................................................. 182
5.3.1 Hints .............................................................................................................................. 185
5.4 Error display in ISPA ............................................................................................................... 186
6 Technical Interface Description ............................................................................................... 187
6.1 Communication technology ..................................................................................................... 187
6.2 XML Schemes ......................................................................................................................... 187
6.3 Authentification and authorization ........................................................................................... 187
6.4 Performance requirements and load tests .............................................................................. 187
6.5 Version Lookup ....................................................................................................................... 188
6.6 Logging .................................................................................................................................... 188

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 6
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

6.7 Connection Detection .............................................................................................................. 189

7 Content of delivery .................................................................................................................... 190
8 Change Log ................................................................................................................................ 191
8.1 Changes from version 3.1.0 to version 3.1.x ........................................................................... 191
9 List of open items and future developments .......................................................................... 194
10 Abbreviations ............................................................................................................................. 195
11 References ................................................................................................................................. 196

Table of figures
Figure 1: The service process with the interaction between ISPA and DMS ........................................ 12
Figure 2: Sequence diagram ................................................................................................................. 16
Figure 3: Sample XML schema ............................................................................................................. 17
Figure 4: Interface overview in the ISPA environment (bold red arrow marks the scope of the interface
contract) ......................................................................................................................................... 23
Figure 5 Service Process and Order Handling ...................................................................................... 24
Figure 6: Edit window for customer/vehicle data in ISPA ..................................................................... 26
Figure 7: Sequence diagram setup values ............................................................................................ 32
Figure 8: Sequence diagram searchCustomer.................................................................................. 33
Figure 9 Customer-Vehicle relationship in DMS and ISPA ................................................................... 34
Figure 10: Sequence diagram to get the customer details ................................................................... 35
Figure 11 Sequence diagram addCustomer ....................................................................................... 36
Figure 12: Sequence diagram changeCustomer................................................................................ 37
Figure 13: Sources for work items and parts in the ISPA interface ...................................................... 39
Figure 14: Example for a complex work items list ................................................................................. 40
Figure 15: Window DMS catalogue in ISPA .......................................................................................... 41
Figure 16: Adding a local FRU .............................................................................................................. 43
Figure 17: Adding a local SRP .............................................................................................................. 44
Figure 18: Input a part by the part number directly in the window Entering services and vehicle data 45
Figure 19: Sequence diagram add part by direct input of the part number .......................................... 45
Figure 20: Direct adding of a FRU......................................................................................................... 46
Figure 21: Display of prices in ISPA ...................................................................................................... 49
Figure 22: Sequence diagram price information ................................................................................... 51
Figure 23: Items catalogue with order split in ISPA .............................................................................. 52
Figure 24: Sequence diagram check parts availability .......................................................... 53
Figure 25: Dealer with branches and storage places ............................................................................ 54
Figure 26: Display of the parts availability in ISPA................................................................................ 55
Figure 27: The customer statement editor in ISPA (VFC based) .......................................................... 61
Figure 28 “To be” exchange of the order base between ISPA and DMS.............................................. 62
Figure 29 Scope of the synchronisation modes .................................................................................... 63
Figure 30 State diagram for order's synchronization status with sync modes ...................................... 66
Figure 31 Sequence diagram illustrating order creation and release ................................................... 67
Figure 32 Example Sequence Diagram of ISPA Synchronization Dialog ............................................. 68
Figure 33: Sequence diagram storeNewOrderBase ......................................................................... 70
Figure 34: Mapping of the element names of the XML schema to the printed information .................. 72
Figure 35: Formatting and positioning of the Q-wording in the workshop order printout ...................... 73
Figure 36: Sequence diagram get order status ..................................................................................... 73

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 7
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 37: Display of order base details in ISPA................................................................................... 73

Figure 38: Sequence diagram get order base ....................................................................................... 74
Figure 39: Sequence diagram getOrderList .................................................................................... 75
Figure 40: DMS job list with button to input the qualified workshop statement (suggestion) ................ 78
Figure 41: Method getSetupValues .................................................................................................. 79
Figure 42: Structure of method getSetupValuesResponse (LF 4) .................................................. 81
Figure 43: Structure of the flexible field list ........................................................................................... 84
Figure 44: Structure of a customer/vehicle search request .................................................................. 88
Figure 45: Structure of searchCustomerResponse .......................................................................... 89
Figure 46: Structure of the method getCustomerDetails ............................................................... 91
Figure 47: Structure of the method getCustomerDetailsResponse .............................................. 92
Figure 48: Structure of method addCustomer ..................................................................................... 93
Figure 49: Structure of the method addCustomerResponse ............................................................. 95
Figure 50: Structure of the method changeCustomer ........................................................................ 96
Figure 51: Structure of the method changeCustomerResponse ....................................................... 97
Figure 52: content of method getLocalFlatRateGroupList ......................................................... 98
Figure 53: content of method getLocalFlatRateGroupListResponse........................................ 98
Figure 54: Content of method getLocalFlatRateGroup ................................................................. 99
Figure 55: Content of method getLocalFlateRateGroupResponse ........................................... 100
Figure 56: Structure of method getLocalFlatRateDetails......................................................... 101
Figure 57: Structure of method getLocalFlatRateDetailsResponse ....................................... 102
Figure 58: Content of method getLocalSRPGroupList ................................................................. 102
Figure 59: Content of method getLocalSRPGrouListResponse .................................................. 103
Figure 60: Content of method getLocalSRPGroup .......................................................................... 103
Figure 61: Content of getLocalSRPGroupResponse ..................................................................... 104
Figure 62: Content of getLocalSRPDetails................................................................................... 104
Figure 63: Content of method getLocalSRPDetailsResponse .................................................... 105
Figure 64: Content of method getLocalPartDetails ................................................................... 106
Figure 65: Content of method getLocalPartDetailResponse .................................................... 107
Figure 66: Content of method getPriceInformation ................................................................... 108
Figure 67: Element <package> in request <getPriceInformation> .......................................... 110
Figure 68: Content of method getPriceInformationResponse .................................................. 112
Figure 69: element packagePrice ................................................................................................... 112
Figure 70: Content of method checkPartsAvailability ............................................................. 114
Figure 71: Content of the method checkPartsAvailibilityResponse ..................................... 116
Figure 72: Structure of method getOrderBase ................................................................................ 117
Figure 73: Structure of the method getOrderBaseResponse ......................................................... 119
Figure 74: Content of method checkOrderBaseStatus ................................................................. 120
Figure 75: Content of method checkOrderBaseStatusResponse ................................................ 121
Figure 76: Structure of method getOrderList ................................................................................ 122
Figure 77: Structure of method storeNewOrderBase .......................................................................... 125
Figure 78: Structure of the method storeNewOrderBaseResponse .............................................. 127
Figure 79 Structure of method updateOrderHeader ........................................................................... 128
Figure 80 Structure of the updateOrderHeaderResponse .................................................................. 129
Figure 81 Structure of method releaseOrder (LF4) ............................................................................. 129
Figure 82 Structure of method response releaseOrderResponse (LF4)....................................... 130
Figure 83 Structure of resetOrderChangeFlag (LF 4) ......................................................................... 130

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 8
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 84 Structure of resetOrderChangeFlagResponse ................................................................... 131

Figure 85 Structure of method addJob............................................................................................... 131
Figure 86 Structure of method response addJobResponse ............................................................... 133
Figure 87 Structure of method cancelJob ........................................................................................... 133
Figure 88 Structure of method response cancelJobResponse ........................................................... 134
Figure 89 Structure of method printOrderBase (LF4) ................................................................... 135
Figure 90 Structure of method response printOrderBaseResponse (LF4) .................................. 136
Figure 91: Structure of type typeSchemaVersion ........................................................................... 137
Figure 92: Structure of dealertype .................................................................................................. 137
Figure 93: Structure of type typeUserInformation ...................................................................... 138
Figure 94: Structure of a vehicle reference ......................................................................................... 139
Figure 95: Structure of vehicle identification number .......................................................................... 140
Figure 96: Values with units ................................................................................................................ 140
Figure 97: Structure of mileage ........................................................................................................... 141
Figure 98: Structure of customer result (1) ......................................................................................... 142
Figure 99: Structure of customer result (2) ......................................................................................... 143
Figure 100: Structure of customer detail ............................................................................................. 145
Figure 101: Structure of vehicle details ............................................................................................... 146
Figure 102: Type typeFlatRatePriceRequest ............................................................................ 147
Figure 103: Type typePartPriceRequest ..................................................................................... 147
Figure 104: Type flatRatePriceEntry ......................................................................................... 148
Figure 105: Type typePartPriceEntry ......................................................................................... 149
Figure 106: Structure of the order base <typeOrderBaseRead> (LF 4) ......................................... 150
Figure 107 Structure of the order base <typeOrderBaseWrite> (LF 4)............................................... 151
Figure 108: Structure of the vehicle information within order base ..................................................... 152
Figure 109 Structure of type <typeJobRead> (LF4) ......................................................................... 154
Figure 110 Structure of type <typeJobWrite> (LF4) ....................................................................... 155
Figure 111: Structures of the job list <typeJobListRead> und <typeJobListWrite> (>= LF3)
..................................................................................................................................................... 155
Figure 112: Structure of typePartRead ............................................................................................... 156
Figure 113 Structure of typePartWrite ................................................................................................. 157
Figure 114 Structure of <typeSplitInformation> .................................................................................. 158
Figure 115: Structure of customerStatement ...................................................................................... 158
Figure 116: Structure of typeFlatratUnitRead ..................................................................................... 159
Figure 117 Structure of typeFlatRateUnitWrite ................................................................................... 160
Figure 118: Structure of typePackageRead (SRP) LF 4 ..................................................................... 161
Figure 119 Structure of typePackageWrite (LF4)................................................................................ 162
Figure 120 Structure of typePackageFlags (LF4) ............................................................................... 164
Figure 121: Element group groupCustomerCommunication ........................................................ 168
Figure 122: element group groupCustomerAssigned.................................................................... 168
Figure 123: Element group groupCustomerLocation ................................................................... 169
Figure 124: element group groupCustomerPerson ........................................................................ 169
Figure 125: element group groupCustomerBackground ............................................................... 170
Figure 126: Element group groupCustomerCategories ............................................................... 171
Figure 127: Vehicle production details (type typeVehicleProductionDetails) ........................ 172
Figure 128: Vehicle service details (type typeVehicleServiceDetails) .................................... 173
Figure 129: Structure of prices in a price request ............................................................................... 174
Figure 130: Structure of prices in a price response ............................................................................ 175

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 9
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 131: Order Header ................................................................................................................... 176

Figure 132: Structure of the customer specific Price (Detail) .............................................................. 177
Figure 133: Structure of the order split information ............................................................................. 178
Figure 134 Structure of Groups <groupOrderHeader> (including
<groupInvariantOrderHeader> in LF4) .............................................................................. 179
Figure 135 Structure of groupOrderSplit ............................................................................................. 180
Figure 136: General structure of an error ............................................................................................ 181
Figure 137: Display of messages of category REJECT for specific fields .......................................... 186

List of tables
Table 1: Methods overview ................................................................................................................... 20
Table 2: Enhancement for ISPA delivery stage 2 (LF2) ........................................................................ 21
Table 3: Mapping table customer data, ordered as in the ISPA window customer data ...................... 27
Table 4: Mapping table vehicle data, ordered as in the ISPA window customer data .......................... 29
Table 5: List of price types .................................................................................................................... 46
Table 6: Defined simple types ............................................................................................................ 164
Table 7: Error categories ..................................................................................................................... 182
Table 8: List of DMS error codes......................................................................................................... 183
Table 9: Performance requirements for interface methods ................................................................ 187
Table 10: Structure of the method versionLookup ......................................................................... 188
Table 11: Changes from version 3.1.0 to version 3.1.x....................................................................... 191
Table 12: Open items and future developments ................................................................................ 194

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 10
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

1 Introduction

1.1 Aim of an interface contract

The interface contract is used for the controlled and binding reconciliation and harmonization of the
exchange of information between a system which is to be implemented or extended and an external
system which has an interface with the first-mentioned system. The interface contract and represents
the valid and binding agreement between the parties involved.

1.2 Object of the present document

The present interface contract contains the generic functional (business viewpoint) and IT require-
ments for the interface between the BMW Integrated Service Processes Application (ISPA) and a
Dealer Management System DMS via the ISPA Broker. Generic means that each DMS that communi-
cates with ISPA has to meet the requirements of this interface contract when implementing an inter-
face to ISPA. It replaces individual interface contracts between every DMS vendor and ISPA. For de-
tailed information on ISPA see [8], [9].
The target groups are BMW NSCs who roll out ISPA and DMS vendors who implement an interface to
ISPA.
In the main part, the document specifies the interface for the international roll-out of ISPA delivery. The
document already incorporates experiences from the interfaces that have implemented up to now. The
document has undergone a complete revision since the last version. If you have been handed a ver-
sion 2.2 or 3.1 of this contract, it is necessary to reread the document because there were significant
changes. We especially incorporated more precise rules and conventions, especially regarding
• the semantics of XML elements and attributes
• the use respectively the omission of optional elements
• how the DMS is to react on the call of methods from ISPA
• the calculations and the transactions that the DMS has to perform.

Enhancement for several delivery stages (LF2 - LF4)

An overview of the changes is available in Table 2. Enhancements in the XML schemas are explicitly
documented in the schemas themselves and explained in the present document.
DMS vendors who start with the interface implementation will implement the complete scope. DMS
vendors who have already implemented the interface for an earlier delivery stage should verify their
implementation with this document and then implement the enhancements.
The concept of ISPA is described in the system proposal [8]. In case of differences between system
proposals and this interface contract, the interface contract is valid. The interface methods and the
exchanged information are defined by XML schemas (*.xsd files). In case of differences between this
interface contract and the XML schemas, the schema files in their latest released version contain the
valid information.

1.3 Organization of the document

After an introduction to the service process (section 2.1), the principles of the interaction of ISPA with
a DMS are described (section 2.2 to 2.8).
In the main part ISPA functions which interact with the DMS and the XML methods are described in
detail:
• The business context as far as needed for the implementation within a DMS

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 11
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• The methods of the interface communication and the structure of the XML messages for each
function
• The operations that ISPA expects to be performed by the DMS
• Where necessary, the rendering and formatting of output of information within the DMS
Additional requirements on the DMS interface are listed in chapter 4. The error handling is described
in chapter 5. Chapter 6 contains technical aspects of the interface, and a list of open items and further
developments is given in chapter 0.

1.4 Versioning
• The first figure denotes the ISPA delivery version (here: 4). The delivery version is not identic-
al with the system proposal delivery stages (LF1, LF2, LF3, LF4).
• The second figure denotes a significant XML schema change (here: 1). The schemes have
been altered compared to version 3.1.2
• The third figure denotes minor scheme changes and/or documentation changes.
The XML schemes have the corresponding version numbering to the interface contract (section 2.3.1).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 12
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

2 Overview

2.1 The service process

Figure 1 shows the service process and its subprocesses from a customer perspective. Two phases
can be distinguished:
• The phase from the Contact between customer and the dealership to the end of the Service con-
sultation. In this phase ISPA is the leading IT tool to support the person in charge for the reception
and the service advisor. The DMS workshop order is created when the order base is transferred
from ISPA to the DMS.
• The phase from the order processing to the vehicle return is supported by the DMS. Also when the
order is extended, the DMS is the leading system. The service advisor is able to view the order
status and the order catalog.
The phase aftersales operations is currently supported by the DMS.
The processes are described in the following paragraphs. The interactions between ISPA and the
DMS are introduces where they typically take place.

Tele Key …
KSD EPC ASAP FBM ISTA
Service Reader
ISPA

Order creation with

Contact Appointment Consultation Service ISPA-initiated
scheduling preparation consultation workshop order
printout by the DMS
Order Transfer Aftercare
Accessories
qualification order status operations
consultation
DMS and (enhanced)
Workshop
order order content

Addition of
Order Vehicle
local labors Invoicing
processing return
Customer/ and parts Price and
vehicle data provided by stock
DMS management the DMS information

ISPA service case data object (appointment)

DMS order data object
Data object life cycle
Figure 1: The service process with the interaction between ISPA and DMS
During the Consultation preparation and the service consulting the service advisor adds labors and
parts from different sources:
• BMW flat rate units and service repair packs from KSD (Kaufmännische Sercicedaten DVD)
• Parts from EPC (electronic parts catalogue)
• Local labors and parts from the DMS
Several interfaces to other IT systems provide additional information:
• Data from teleservice calls from Teleservices
• Vehicle key data read by the KeyReader and interpreted by the KeyInterpreter
• Information from ASAP (Aftersales Assistant Portal)
• SAs, individual data and the repair history from FBM (Fahrzeugbeschreibungsmodul)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 13
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• Dealer and startup data from the ISIS integration platform

Contact
The service process starts with the process Contact. The contact is made between the customer and
the dealer organization when one of these events happens:
Making personal contact the case of non-availability of the KeyReader functionality
Making personal contact with availability of the KeyReader functionality
Making contact via TeleServices
The aftersales service actively contacts the customer, e. g. by a telephone call.

Appointment scheduling
The DMS is the leading system for customer and vehicle data. The person in charge for the reception
or the service advisor use ISPA to identify customer and vehicle. ISPA interacts with the DMS to
• search a customer / vehicle
• change a customer / vehicle
• add a customer / vehicle
As long as the customer/vehicle data are incomplete, that is not all mandatory fields of the DMS can
be filled, the customer/vehicle data may be cached within ISPA and not yet transferred to the DMS.
When customer and vehicle are identified, the responsible person in the phase Appointment schedul-
ing
• records and updates the kilometer reading of the vehicle (with or without KeyReader / KeyIn-
terpreter, see phase Contact),
• notes the information whether or not the vehicle is towed to the dealership,
• checks the telephone number of the customer,
• selects service and repair tasks, e. g. from the workshop catalog,
• records the customer statement (original and qualified),
• checks for open technical campaigns.
In general, one or several repair tasks are selected from the workshop catalogue. Furthermore, the
following items may be added to a vehicle service case:
BMW SRP/FRU from KSD
local SRP/FRU from DMS
parts from EPC
local parts from the DMS
work items and parts to process technical campaigns
work items based on CBS data (condition based service). CBS data are part of the key data and tele-
service call data.
Price and stock information for selected SRPs, FRU items and parts are fetched from the DMS and
displayed in ISPA.
The appointments for service consultation and vehicle return are defined together with the customer.
ISPA's integrated workshop planning feature sets up a rough planning based on the preliminary work
items list.

Consultation preparation

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 14
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The process Consultation preparation shall be completed before the customer arrives in the dealer-
ship. A Consultation preparation in advance makes a major contribution to an increasing process and
service consultation quality. Numerous system-based features (see above) are provided here.
The selected service and repair tasks can be supplemented to include additional repair tasks, SRPs,
FRU items and/or parts. In general, positions from the ISPA workshop catalogue are qualified. This
means that they are detailed and replaced by SRPs, FRU items (taken from KSD or DMS) and parts
(taken from EPC or DMS).
Part of the Consultation preparation is to define the cost units for jobs and single items and eventually
split the order to several different cost units. Examples for cost units are leasing company, warranty
and Service Inclusive.
If it has not been possible to do the consultation preparation in advance it is performed during the Ser-
vice consultation, the customer being present.
Price and stock availability information for parts is requested from the DMS and displayed automatical-
ly.

Service consultation
The service advisor receives the customer. The service advisor explains the notes from the Appoint-
ment scheduling and Consultation preparation. The latest key data are read in (if the vehicle key con-
tains key data). Eventually the work items list is updated after the reception of the vehicle.
When service advisor and customer agree on service and repair tasks, the service advisor triggers the
creation of the order within ISPA. All data of the vehicle service case that are relevant to the order,
including the qualified statement1 of the customer, is transferred to the DMS to create an order. The
order is printed by the DMS and signed by the customer. From now on the DMS is the leading system
of the service process.
In parallel, the data of the vehicle business case relevant to FBM, including the qualified statement of
the customer, is transferred to the FBM for storage for the first time.

Accessories consultation
The process Accessories consultation for accessories, parts and lifestyle products has currently no
interactions with the DMS and is not in the scope of this document.

Order processing
The process Order processing is triggered as soon as an order is created, either as the result of the
process service consultation or of the process advice for accessories. This process is supported by
the DMS.
If order changes are necessary the order is enhanced or altered within the DMS. The DMS order sta-
tus is displayed in ISPA. The ISPA user can view, but not change the actual order within ISPA.

Invoicing
After the processing of the order, the order is invoiced. This process is supported by the DMS without
any interaction with ISPA. The DMS order state is set to invoiced when all parts of the orders are in-
voiced. ISPA displays this order state.

1 The qualified statement is a structured problem description (as opposed to the original statement that
just simply contains a string that was entered manually). The core idea is to offer the service advisor a
structured questionnaire during a service consultation. It matches the search structure for PuMA which
is a BMW service information network. ISPA will transmit the full structure of the qualified statement to
the DMS interface which is free to decide whether to use the structure itself or just simply generate a
string from what was passed as an XML structure.
GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011
BMW Group Page 15
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

If the order is split to several cost centers, several invoices are created by the DMS. The order split is
defined by the ISPA user during the phases Consultation preparation and service Consultation.

Vehicle return
The process vehicle return is part of the workshop process and may be supported by ISPA. There is
no interaction with the DMS.

Aftercare operations
The aim of the subprocess Aftercare operations is to make contact with the customer for the purpose
of optimizing customer care (e.g. after a customer visit), in the event of new information regarding the
vehicle or parts and accessories, and in the event of marketing campaigns.
Presently there is no interaction with the DMS.

2.2 The communication concept

The technical communication is based on SOAP (see section 6.1).
The communication is always triggered by ISPA. ISPA sends a request to a software component
called ISPA broker which runs on the ISIS platform (for more information see [10][11]). The ISPA bro-
ker directs the request to the DMS. The DMS answers with a response, which in its turn is handled by
the ISPA broker and sent back to ISPA. The inner workings of Score broker are not relevant for the
implementation of the interface and therefore it will not be discussed any further in this document.
Since there always has to be a response the methods are pairs with the naming convention:
• Request: methodCalledByISPA
• Response: methodCalledByISPAResponse
There is no case in which communication between DMS and ISPA is triggered by the DMS, except
methods regarding the workshop statement.
The interaction between ISPA and DMS is illustrated by diagrams that follow the syntax of UML se-
quence diagrams (Figure 2). The ISPA broker is omitted in all diagrams where it just routes communi-
cation through and does not act itself.
An interaction of ISPA and the DMS is triggered by the ISPA system or the ISPA user. The user per-
forms a user action in an ISPA window. The ISPA system then calls a method of the interface (me-
thodCalledByISPA) and sends an XML instance to the DMS. Often the DMS has to perform opera-
tions itself, e. g. calculate a price. The DMS then constructs the answer, creates the response XML
instance and sends it back by the method methodCalledByIspaResponse. Eventually ISPA has to
perform some operations, too, before the results are displayed in ISPA.
In some cases several interface interactions are triggered automatically by one user interaction.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 16
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 2: Sequence diagram

The same requests may be sent by several business functions. But the response is always the same
so that the implementation of the interface does not need to have a complete understanding of the
business functions.
There is no session concept, i.e. all requests and responses contain all data that are needed to handle
them.

2.3 XML schemes and instances

2.3.1 XML schemes

A good know-how in XML and especially in XML schema definition is required to understand and im-
plement the DMS interface. A scheme defines a grammar for the XML instances (messages) that are
exchanged between ISPA and the DMS.
Relevant schemes are found in 4.1.

Graphical representation
In Figure 3 a sample XML scheme introduces the most important graphical elements and should be
self-explaining.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 17
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 3: Sample XML schema

Structure of the XML schemes

The XML schemes consequently use type definitions. Three categories of types are used:
• XML standard types
restricted standard types, mainly string types with a restricted length, namespace xs:simpleType
GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011
BMW Group Page 18
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

complex types for ISPA specific content, namespace xs:complexType

There are key objects that are identified by identifier elements. They may not be changed neither by
ISPA nor by the DMS once they are set. They are listed here to introduce the principle of identifier
elements and will be explained in detail later in their semantic context:
• The GUID (global unique identifier) which identifies a service case and an order, elements of
type typeGIUD
• The customer number which identifies a customer data set in the DMS, element <customer-
Number>
• The job number which identifies an item of an order base (or a structured group of items) in
the element <jobIdentifier>
• The order of the DMS, which is linked to a service case, is identified by the element <order-
Number> (as well as by the GUID).
• Element groups are used to group elements which belong together. A group is used in several
methods. This facilitates the management of schemes in case of the further development.
• To distinguish a database entry in both ISPA and the DMS from an XML element and an XML
attribute, a database entry is called field in this document.

2.3.2 Conventions for XML instances

XML has to be wellformed, especially the following basic rules must be fulfilled by DMS, here some
basics:
• Case sensitive XML element and element attribute names
• Sequencing of XML elements
• XML element orders
• XML must follow XML schema description
• Ignore whitespaces
• XML parser library recommended (Xerces1/2, JAXP, JAXB, Saxon, Libxml)
• UTF-8 encoding (HTTP header, XML start tag) recommended
• Non-printable chars in UTF-8 are not allowed (<= hexadecimal 20)
Additionally to the XML schemes the following conventions apply for XML instances:
• Optional elements are generated only if they have a content as far as possible.
• An element with no content means that the element is explicitly empty.
• An optional element which is omitted means that the corresponding field in ISPA or in the
DMS, if existing, is not changed.
• An element which is transmitted, either mandatory or optional, means that its content replaces
the content of the corresponding field in the target system.
• Consequence: An empty element deletes the contents of an existing corresponding attribute.
• The instances should consist as far as possible only of optional elements which carry informa-
tion. This increases the performance and facilitates the validation of the XML messages.
• Nevertheless the DMS and ISPA must be able to read any valid instances whether optional
elements are currently in use or not.
An element which is optional in the XML scheme may be defined mandatory by the business side. For
example, the vehicle identification number is optional in the complex type typeVehicleDetails, but
mandatory by the business as the central identifying attribute of a vehicle.
Many optional elements are currently not in use. Some are deprecated and will be discontinued in
further releases of the XML schemes. Others are made available for future use. Wherever possible,
this document and the annotations of the XML schemes give information of the use.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 19
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

2.3.3 XML instance samples

Most of the XML constructs are illustrated by sample listings. All XML instances are SOAP messages
(chapter 6). A SOAP message has the structure of Sample 1. For the purpose of compact samples,
only the content within the <SOAP-ENV:Body> element will be listed.

<SOAP-ENV:Envelope SOAP-
ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<checkPartsAvailabilityResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" refSchema="scoreDMSgeneric" version="04.00.06"/>
<partsAvailability>
<partNumber>51348159171</partNumber>
<numberOnStock>0.00</numberOnStock>
<availabilityFlag>false</availabilityFlag>
</partsAvailability>
</checkPartsAvailabilityResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Sample 1 Structure of a SOAP message

Often the messages contain element structures which are transmitted in many methods and are not
relevant to the explanation of a specific context. To shorten the listings these structures are often omit-
ted. The omissions are marked with ... (Sample 2).

<checkPartsAvailabilityResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" refSchema="scoreDMSgeneric" version="04.00.06"/>
<partsAvailability> ... </partsAvailability>
</checkPartsAvailabilityResponse>

Sample 2 Omissions in a listing of an XML instance

2.3.4 Handling namespaces

Your XML parser should support all XML namespaces, e.g.:
<SOAP-ENV:Envelope xmlns:SOAP-
ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
The following namespace is the same but xsd is referenced:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

2.3.5 Concurrency in overlapping Webservice requests

Be sure to include tests with several different clients (or test tools) sending XML requests to the inter-
face at the same time. The interface has to work properly with overlapping requests.
If simultaneous processing of multiple requests is not possible, serialization of incoming requests and
buffering of waiting requests has to be implemented and tested by the interface.
A user may open several ISPA sessions at the same time, i.e. the interface has to cope with several
requests from the same user coming in at the same time.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 20
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Note: File locking issues and buffer overruns (buffer of waiting requests is full) might be possible pit-
falls.

2.4 Method overview

In Table 1 an overview over the methods is given. Only those methods are listed that ISPA sends to
the DMS. In all cases the DMS answers with a method of the name callingMethodResponse.
Table 1: Methods overview

Function Calling Method Section

Customer/vehicle identification
Get setup values from the DMS for mandatory getSetupValues 3.4.4
attributes and attribute value lists
Search customer and vehicle data searchCustomer 3.4.5
Get details of a customer/vehicle data set getCustomerDetails 3.4.5
Add a new customer and/or vehicle addCustomer 3.4.7
Change data of a customer and/or vehicle changeCustomer 3.4.8
Work items and parts
Get a list of local SRP groups for a given VIN getLocalSRPList 3.5.2.3
Get a list of local SRPs for a SRP group getLocalSRPGroup 3.5.2.3
Get details of a local SRP getLocalSRPDetails 3.5.2.3
Get a list of flat rate groups for a given VIN getLocalFlatRateGroupList 4.2.6
Get a list of flat rates for a flat rate group getLocalFlatRateGroup 4.2.7
Directly add an SRP position from DMS data getLocalSRPDetails 4.2.11
Directly add a flat rate unit position from DMS data getLocalFlatRateDetails 4.2.8
Directly add a part position from DMS data getLocalPartDetails 4.2.12
Get price information getPriceInformation 3.5.4
Check the number of parts available in all checkPartsAvailability 3.5.8
branches
Orders
Create an order storeNewOrderBase 3.6.7
Get the DMS status of an order checkOrderBaseStatus 3.6.17
Get an order with all positions from the DMS getOrderBase 3.6.18
Get a list of orders from the DMS getOrderList 4.2.17
Release (finalize) a DMS order releaseOrder 3.6.23
Updates DMS order header before (>= LF3) updateOrderHeader 3.6.21
Prints DMS order header (<LF3 only integrated in printOrderHeader 3.6.16.1
storeNewOrderBase)
Informs ISPA about sync status change in resetOrderChangeFlag 4.2.21
DMS from “updatedInvoice” back to “in-
voiced” (SRP Monitoring)
Note: The status updatedInvoice and the
method resetOrderChangeFlag are re-
served for future use. DMS implementing
according to this interface contract are
not required to implement this status and
method.
Jobs in Orders (>= LF4)
Adds a job to a DMS order addJob 3.6.22.1
Removes one or more jobs from DMS order cancelJob 3.6.22.2

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 21
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Other changes initiated by change request “SRP Monitoring” will be defined in change request docu-
ment.

2.5 Enhancements for ISPA delivery stage 2 (LF2)

Table 2 lists the enhancements for ISPA delivery stage 2. This list is intended for the DMS vendors,
which have implemented the interface for LF1, to have a quick overview on the changes of the inter-
face from LF1 to LF2. Enhancements are marked in the text by the line "Enhancement for delivery
stage 2" and a yellow background.
Table 2: Enhancement for ISPA delivery stage 2 (LF2)

Topic Description Section

Customer/vehicle identification
Passing customer New field in the customer data 3.4.2
Not added to the DMS 3.1.7, 3.1.8
Setup values enriched Additional fields from the DMS for customer/vehicle 3.4.2, 3.4.3,
data (Flexfields) for market specific and DMS specif- 4.2.1.7
ic fields
Information which ISPA delivery stage The DMS returns in the element <supportedFea- 3.4.4.2
the DMS supports tureLevel> of method getSetupValuesResponse
the information whether it supports ISPA delivery
stage 1 or 2
Case insensitive search Case insensitive search in the DMS 3.4.5
Blocked customers Blocked customers and customers marked for dele- 3.1.5, 3.1.6
tion in the DMS are not returned by searchCusto-
merResponse, but they are by getCustomerDetail-
sResponse
Getting the customer details From LF2 on the DMS customer number is manda- 3.4.6
tory, the vehicle is optional in a request for customer
details
Getting a list of customer details For use by the soft-nrg software module Aftersales 3.1.6
Manager, a list of customer numbers may be
passed to the DMS to get a list of customer details
Work items and parts
Fixed prices ISPA can set fixed prices and discounts for FRUs, 3.5.5.1
SRPs and parts which supersede prices calculate
by the DMS
Marketing SRP A new type of SRPs, called marketing SRPs, with a 3.5.1, 3.5.4,
fixed price or a fixed cut-off from the price 3.5.4
Third party items A new item type in the work items catalog, e. g. a 3.5.5.3
tow-in service, where a denomination and a price
may be given by the ISPA user
Retail prices The retail gross price is returned to ISPA by the 3.5.4
DMS. Retail gross price and retail net price are
subject to an order split
Request for prices for a list of items To enhance the performance of the interface ISPA 3.5.4
will request the prices of all items together rather
than sending a single request for each item.
Order split A cost center may have several accounts. 3.5.7, 3.6.5
Orders
Vehicle key information is no more The optional information is not used by the DMS 3.6.3.1
transferred to the DMS and will not be transferred any more
Passing customer If the customer of an order base is marked as a 3.6.3.2
passing customer, the complete customer/vehicle
data set is transferred to the DMS as part of the
order base
Planned return date and service advi- Added to the order base information 3.6.16.1
sor for the vehicle return

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 22
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Topic Description Section

Dealer data to correctly create the Added to the order base information
order number
Expected return date The expected return date (if available) is given by 3.6.17
the DMS to ISPA and displayed in ISPA
Get a list of orders from the DMS The ISPA synchronizer requests a list of DMS or- 0
ders in order to store them into the FBM system
Other

Qualified statement technician Requirements are provided to supplement the quali- 3.7
fied statement customer with a qualified statement
technician. The management of the qualified state-
ment technician is triggered by the DMS.
Error handling Detailed requirements for the element handling and 5
error list defined
Performance requirements Requirements for response times 0

2.6 Enhancements for ISPA delivery stage 3 (LF3)

ISPA light introduced simple job handling for DMS orders (addJob). This will be extended in LF4.

2.7 Enhancements for ISPA delivery stage 4 (LF4)

Order extension has been introduced, more complex job and order handling is available. Schema has
been cleaned up; type definitions were improved and summarized in schema genericTypes.

2.8 System overview

The project ISPA aims to improve the BMW service process and its supporting systems. Figure 4 pro-
vides an overview of the system affected by this interface contract.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 23
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 4: Interface overview in the ISPA environment (bold red arrow marks the scope of the
interface contract)
Important:

The project ISPA and its components have changed their names several times. The following names
represent the same physical component:

ISPA = Score

ISPA Client = KK ISPA = CC ISPA

ISPA Broker = ScoreBroker

2.8.1 Client systems using the interface

Besides ISPA Client other systems may use the same ISPA-DMS interface via the ISPA Broker. The
following alternative clients are known:
• “ISPA light” (reduced ISPA client as webapplication) also uses described interfaces
• “Synchronizer” (transfer to repair history)
These systems are not to be treated as special clients from a DMS point of view: The same interface
behavior is expected, and all requests will run via the ISPA Broker the same way it works with ISPA
Cient.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 24
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3 Functional Description of Interface Features

3.1 Basic Philosophy

The interface will allow the user to perform all tasks that are needed for a service consultation. The
service assistant and the service advisor are the roles that are intended to be completely covered by
this interface. These users should be able to perform the same work using ISPA with the interface that
they would otherwise do in the DMS user client.
This means:
- Orders, customers and vehicles created or changed via the interface should be exactly in the
same state like an order, customer or vehicle created or changed manually in the DMS Client.
It should for example not be necessary to manually update all order lines after the order has
been received via the interface.
- The user should have the same privileges via the ISPA-DMS interface that he has when work-
ing inside the DMS Client. The ISPA-DMS interface should not become a backdoor nor should
users be hampered when working via the interface.

3.2 Introduction: Overview functional features and technic-

al interface methods
This overview links usecase areas to technical interface calls (webservice requests). For example you
can see that the webservice request searchCustomer is related to the field “Customer/Vehicle Da-
ta”.
Abbildung explain invoice ist hier falsch. Richtig: Auftragsverfolgung hinsichtlich Inhalt und Status

Figure 5 Service Process and Order Handling

This chapter offers process-oriented feature descriptions, followed by a technical description chapter
with detailed webservice information.

3.3 Permissions of method access and workflow continuity

ISPA uses DMS features for order handling, pricing information, service history preparations and so
on. It is very important that ISPA owns the same access rights and permissions as a DMS user. Espe-
cially every workflow step (e.g. storing a new order base or removing order positions, searching cus-
tomer details and so on) implemented in DMS should lead to the same results and DMS behavior
compared to DMS actions carried out by a DMS user. There has to be no additional DMS limitation or
permission management on top of this default access handling.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 25
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Example: a vehicle search request by ISPA using DMS should result in same facts as a DMS search
query executed by a DMS user.

3.4 Customer/vehicle identification

3.4.1 Customer/vehicle data

The DMS is owner of the customer/vehicle data and the leading system regarding the management of
this data. ISPA caches the customer/vehicle data. That means ISPA holds a copy of the data which is
updated from the DMS when ISPA uses this data.
As long as the customer/vehicle data is incomplete, however, it may be stored in ISPA only. Incom-
plete data may exist in the processes Contact and Consulting preparation. For example, a customer
calls the service assistance and he or she only notes the name, the telephone number and the regis-
tration no, but the DMS requires more mandatory fields for customer creation. In this case the custom-
er/vehicle data record has to be completed at latest by the end of ther service consultation and added
to the DMS not until the order base is created in the DMS.
In ISPA the customer/vehicle identification refers to one type of customer only. The customer is de-
fined as the keeper of the vehicle. A distinction between owner, keeper and driver is not made within
the scope of ISPA.
A database entry in ISPA and in the DMS is denoted as field in this interface contract, whereas the
words element and attribute are reserved for the XML side.
There are different sets of fields in both systems.
• Many fields are common to ISPA and the DMS.
• A few exist only in ISPA and are not relevant to the DMS (e. g. Display the customer name in
the welcome terminal)
• Some may exist only in the DMS. They are not relevant to the interface.
• Some DMS fields do not exist in standard ISPA but are relevant for the interface. These are
handled as flexible fields (section 4.2.1.7).
Figure 6 shows the ISPA window Customer data. There are mandatory and optional fields. The fields
that are mandatory in the DMS are marked (here in a blue font).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 26
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 6: Edit window for customer/vehicle data in ISPA

The mandatory fields of ISPA are just
• Name (for the customer)
• Model (for the vehicle)
Which DMS fields are mandatory is defined by the DMS itself. ISPA checks whether values are given
for these mandatory field before a customer/vehicle data set is transferred to the DMS. Therefore
ISPA has to know these fields and reads them from the DMS (section 3.4.4).
Many DMS determine certain field contents by themselves. For example they set the model code and
the series automatically when the VIN is given. These fields must be optional in ISPA.
Further the DMS may provide value ranges for customer/vehicle attributes (mandatory or optional). If a
value range is given, only a value of this list can be set by the user. If no value is given, the DMS may
set a default value. ISPA has to know the value lists and the associated fields and reads them at the
start of the client (section Figure 6).
ISPA provides three functions for the customer/vehicle identification which interact with the DMS:
• Search customer/vehicle (section 3.4.5)
• Add customer/vehicle (section 3.4.7)
• Update customer/vehicle (section 3.4.8)
The field “Passing customer” is added. It indicates whether a customer will be stored in the DMS data-
base. The default is "no". If it is set to "yes" the methods addCustomer and changeCustomer will
not be applied. Instead the customer/vehicle data is transferred to the DMS within the creation of an
order.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 27
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.4.2 Customer data

Table 3: Mapping table customer data, ordered as in the ISPA window customer data

Name in the XML scheme element XML scheme type / Content Comment
ISPA GUI name format
Customer customerNumber typeCustomerNumber DMS specific cus- Key attribute,
number : NMTOKEN tomer number always set by the
DMS, identifies
the customer data
set
Social securi- socialSecurityNumber typeVarchr_60 Social Security or Needed in some
ty number National Insurance markets, e. g.
Number as national France
identifying number
Matchcode matchCode typeVarchr_120 Shortcut value for the Presently not
actual customer used by sear-
chCustomer
Salutation salutationCode typeVarchr_20 Salutation like Mr, Unique internal
Mrs code; see getSe-
tupValues
Title titleCode typeVarchr_20 Title like Prof., Dr. Unique internal
code; see getSe-
tupValues
Name lastName typeVarchr_120 If the partner is a
legal person the field
is the company name,
otherwise the field
has the last name of
the person
First name firstName typeVarchr_120 If the partner is a
legal person the field
is empty, otherwise
the field has the first
name of the person
Passing isPassingCustomer boolean Flag if the customer is New in LF2: A
customer a passing customer, passing customer
default is "no". is not added to the
DMS database.
Driver driver string Name of the driver if Just a string, not a
different from the relation to a per-
keeper son object
Address 1 address1 typeVarchr_120
Address 2 address2 typeVarchr_120
Address 3 address3 typeVarchr_120
Address 4 address4 typeVarchr_120
Address 5 address5 typeVarchr_120
Postal code postCode typeVarchr_60
Town / city city typeVarchr_120
County county typeVarchr_120
Country country typeVarchr_120
Telephone telPrivate typeVarchr_60
(home)
Telephone telCommercial typeVarchr_60
(work)
Mobile phone mobilePrivate typeVarchr_60
(home)
Mobile phone mobileCommercial typeVarchr_60
(work)
Note customerInformation string Some free text e.g.
best customer

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 28
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Name in the XML scheme element XML scheme type / Content Comment
ISPA GUI name format
Additional furtherNotes typeVarchr_60 e.g. Likes coffee
notes
Customer customerIndicator typeVarchr_60 Various indicators for
feature customer
Credit indica- creditIndicator boolean true if the customer is
tor eligible for credit
Payment paymentMethod typeVarchr_60 The payment method
type the customer pays
with, e.g. cash direct,
invoice
Credit limit creditLimit typeCurrency : Credit limit
xs:decimal
Last contact lastContactDate xs:date
Supporting companyName typeVarchr_60
company
Supporting branch typeBranch: type-
branch Varchr_20
Language languageCode typeVarchr_20 unique internal
code; see getSe-
tupValues
Fax (home) faxPrivate typeVarchr_60
Email (home) emailPrivate typeVarchr_60
Initials initials string Initials of the person
Date of birth birthDate xs:date
Place of birth birthPlace typeVarchr_60
Driving li- driversLicenceValidi- xs:date
cense validity tyDate
date
Hobby hobby typeVarchr_60 Free description for a
hobby - if the person
is a legal person the
field is empty
Company isCompany boolean TRUE for legal per-
customer sons like companies,
FALSE for natural
persons.
Allocated advisingCompany string
company
Allocated advisingBranch string
branch
Fax (work) faxCommercial typeVarchr_60
Email (work) emailCommercial typeVarchr_60
Customer customer group e.g. 0 till unbound occur- customer group e.g.
group employee.. rences : string employee..
Occupational profession typeVarchr_60
group
Industry professionBranch typeVarchr_60 e.g. IT
sector
Preferred preferredContactMe- typeVarchr_60
contact thod
Federal state state typeVarchr_120
Sex genderCode typeVarchr_20 the gender code of
the person if the per-
son is a natural per-
son
Bank details bankingAccount typeVarchr_120 Banking Account of
the customer

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 29
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Name in the XML scheme element XML scheme type / Content Comment
ISPA GUI name format
VAT ID vatRegNumber string registration number of
the value added tax
(VAT)
VAT group vatGroupCode typeVarchr_20 Unique internal
code; see getSe-
tupValues
Tax number taxPayersAccount- typeVarchr_60 Identification of the
Number customer in the fiscal
authority (CIF in
France, Part. IVA in
Italy)
Information
regarding
occupational
group
Creation date allocatedDate date
Last change lastChange date
date
Display in – – ISPA internal attribute
Welcome
terminal
Display in isAftersalesMarke- Boolean
Aftersales tingBlocked
Marketing
– vehicleReference typeVehicleDetails one or more sets of see Table 4
vehicle data

Note the element groups where name end with Result in the following structure figures. Element of
these groups are also returned by the DMS as a search response (section 3.4.5).
The element type typeCustomerDetail defines the customer data structure (Figure 100). The sub-
structures define groups of the customer attributes. The optional list of vehicleReference establishes
the relation to the vehicle(s) which belong to a customer (see 3.4.3).
The boolean element <isPassingCustomer> is added. It indicates whether the customer is a pass-
ing customer or not. The default is "no". If set to "yes" the methods addCustomer and changeCus-
tomer are not called and no customer is created in the DMS. Instead the customer and vehicle data
are transferred to the DMS when the order is created.
The passing customer concept is not supported by all DMS systems. Therefore it is configurable in the
ISPA console whether the field Passing Customer is presented to the ISPA user or not. It is not pre-
sented, the default value "no" is automatically set.
See type typeCustomerDetail in 4.3.10. Address dates are stored in the element group group-
CustomerLocation (Figure 123). The attributes address1, postCode and city usually are man-
datory attributes in the DMS. Personal data are stored in the element group groupCustomerPerson
(Figure 124). More information about the customer are stored in the element group groupCustomer-
Background (Figure 125). Further information, especially commercial information, about the custom-
er is stored in groupCustomerCategories in Figure 126.

3.4.3 Vehicle data

Table 4: Mapping table vehicle data, ordered as in the ISPA window customer data

Name in the XML schema element XML scheme Content Comment

ISPA GUI name format
Make brand typeBrandOpen : brand of the Brand type open to corpo-
string vehicle rate external brands. Con-
tains the values of type-

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 30
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Name in the XML schema element XML scheme Content Comment

ISPA GUI name format
Brand (corporate brands)
or others defined by the
DMS
See section 4.2.1.5 for a
list of BMW group brands
Model modelDesignation string designation of
the vehicle
model, e.g.
320d
Model code modelCode string contains the
code for the
model, e.g.
AL71
Series devSeriesCode string Development
series code,
e.g. E30
Kilometre mileage typeMileage See section 4.3.7 for the
reading type
Registration numberPlate string
no.
VIN vin VIN as flat String
without prefix and
vinShort
Engine num- engineNumber typeVarchr_20
ber
Gearbox code gearCodeLetter typeVarchr_20
letter
Fuel type – – ISPA internal attribute
First registra- registrationDate date
tion
Last registra- readmissionDate date
tion
Warranty ex- extensionOfGuaranteeTo date
tension
MOT legalInspectionDate date next legal in- used in the UK, eventually
spection also USA
Emissions test emissionControlInspec- date
tionDate
Next BSU nextBSUAppointment date Date of next
appointment extraordinary
brake check
Last service – – ISPA internal attribute
appointment
Last service – – ISPA internal attribute
advisor (DMS)
Service type serviceType typeVarchr_20
Next service nextMaintenanceDate date
(date)
Next service nextMaintenanceDis- typeMileage See section 4.3.7 for the
(km) tance type
Next timing nextChangeOfGearBelt- date
belt change Date
(date)
Next timing nextChangeOfGearBelt- typeMileage See section 4.3.7 for the
belt change Distance type
(kilometre)
Next brake nextChangeOfBreak- date
fluid change FluidDate

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 31
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Name in the XML schema element XML scheme Content Comment

ISPA GUI name format
Date of manu- manufacturingDate date
facture
Date of deli- deliveryDate date
very
Colour code colour attribute code :
string
Colour colour typeVarchr_120 colour of the
vehicle varnish
Upholstery upholstery attribute code :
code string
Upholstery upholstery typeVarchr_120 upholstery of
the vehicle
Lead type guideType typeVarchr_20 Lead type ac-
cording to KSD
logic
Pseudo type pseudoType typeVarchr_20 Service type
according to
KSD logic
Comment notice typeVarchr_120 not used in ISPA
Sold here selfSale typeVarchr_60
Sales repre- vendorName typeVarchr_60
sentative
Sales repre- vendorNumber typeVarchr_20
sentative
number
– engineType typeVarchr_20 not used in ISPA
One customer may have assigned zero or more vehicles. As mentioned above, the customer in ISPA
is defined as the keeper of a vehicle (not owner, not driver). The relation between customer and ve-
hicle(s) is given via the element vehicleReference of type typeVehicleReference, which is a
subelement of the element customerDetail of type typeCustomerDetail (Figure 100).
The structure of the vehicle data is shown in type typeVehicleDetails in 4.3.11. Note the element
groups where the name ends with Result in the following structure figures. Element of these groups
are also returned by the DMS as a search response (section 3.4.5).

3.4.4 Configuration of customer and vehicle data

3.4.4.1 Adapting the field set

ISPA comes with a proprietary set of customer and vehicle fields, see Table 3 and Table 4. Each of
the field corresponds to an element in the XML schemes.
A DMS as well comes with its set of customer and vehicle data fields. In order to exchange these data
the following items must be taken into account in order to adapt (customize) the field set.
• DMS is the owner of the customer and vehicle data and is responsible for their consistency.
• ISPA possesses mandatory fields which the system requires. It is just the customer name and
the vehicle model.
• DMS possesses mandatory fields.
• DMS may possess fields that do not exist in ISPA but are mandatory or input shall be possible
in ISPA.
• The type of corresponding fields in either system may differ, for example the allowed string
length.
• DMS may fill fields automatically from the values of other fields, for example the type may be
set when the VIN is given.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 32
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• The names of corresponding fields may differ.

• DMS may have defined a value list for a field. Either only values of the list may be set or the
list is a suggestion but other values are accepted, too. ISPA does not have this value list.
• DMS may prescribe the format of field values, for example a date format. ISPA has a different
format for the same field.
Fields are grouped by content, for example technical vehicle data, customer communication data. The
position of the fields in window therefore shall be configurable.
Fields have different relevance to the service case, which shall be shown in the user interface. The
position of the fields in window therefore shall be configurable.
These items listed above lead to the requirement for a flexible way to define the exchanged fields and
to a flexible way to present them to the user. Therefore ISPA asks the DMS through the method get-
SetupValues for
• mandatory fields (section 4.2.1.4)
• value ranges for fields (section 4.2.1.5)
• additional fields, called flexible fields (section 4.2.1.7)
During the planning of a roll-out in a market the roll-out team defines and agrees on which fields will be
exchanged between the interfacing systems. The call of the setup values method is based on this
agreement.
The ISPA fields have corresponding elements in the XML schema. No ISPA field can be deleted.

3.4.4.2 Getting DMS setup values

At the start of the ISPA client system console, ISPA requests the setup values and the DMS returns
them (Figure 7).

Figure 7: Sequence diagram setup values

3.4.5 Search customer/vehicle

The search for customer/vehicle data records is triggered by two ISPA user actions:
• The ISPA user is creating a service case in the checkboard and wants to identify the customer
and his vehicle. He searches in ISPA and the DMS whether the customer/vehicle data set al-
ready exists. If yes, he selects the data set and assigns the customer/vehicle to the service
case.
• The ISPA user maintains customer/vehicle data in the module appointment planner. He
searches in ISPA and the DMS to update data or, if no data is found, to add a new custom-
er/data set.
In either case the sequence of the methods, as far as the DMS is affected, is the same. Figure 8
shows a typical sequence. ISPA features a two-stage search. The first search is executed in the ISPA
database. If the customer/vehicle is not found here a second search is executed in the DMS. As far as

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 33
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

the DMS is concerned, the implementation is straightforward: The DMS receives the request and an-
swers with a results list. Later the DMS receives a request for customer details and returns them
(Figure 8).

3.4.5.1 Use Cases

There are three use cases for searchCustomer in ISPA:
 “Initial Load” of customers and vehicles into the ISPA database for caching (searchCus-
tomer with numberPlate=*). This is performed only once during installation and can also be
done by CSV file import.
 “Existence Check”: If a customer/vehicle record is selected in ISPA that was cached in the
ISPA database, ISPA checks whether the record still exists before it requests details on it. The
search is performed using the VIN. The same request ist also sent to check if the customer
and the vehicle are associated; if not, a warning is issued before a change of ownership takes
place.
 “Customer/Vehicle Search” searches for a customer/vehicle combination using search crite-
ria specified by the user. Possible search criteria are:
VIN, number plate, address lines 1-5, city, first and last name, customer number, e-mail ad-
dress, phone number (any), post code, match code and social security number

Sequence diagram

Figure 8: Sequence diagram searchCustomer

If one single result is found by a search customer, a getCustomerDetail is sent immediately after
the searchCustomerResponse.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 34
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

If no result is found the user gets the DMS search mask. Here he can enter a different search string
and send a new searchCustomer.
If more than one result is found the searchCustomerResponse gives back a list of results. The user
can select one customer/vehicle ore he can cancel. The DMS specifies a maximum result list
If a customer is selected by the user from the ISPA search results list by the user, a searchCusto-
mer is sent with the VIN given. Subsequently a getCustomerDetails is sent automatically.

Owner Customer

1 1
n 1

Car Car

1 Driver as attribute
n

Driver

Typical DMS data model ISPA data model

Figure 9 Customer-Vehicle relationship in DMS and ISPA

The figure above describes the relationship between a vehicle and its owner in DMS and for compari-
son in ISPA. ISPA uses a denormalized view into the customer-vehicle relationship, so that updates
affect two objects inside the DMS. This means that for example change of ownership can be triggered
by addCustomer (with an existing VIN) or changeCustomer (with a customer number that is so far not
associated with the VIN), and that changeCustomer (with an existing customer number and a VIN that
does not exist in the DMS database so far) can create a new vehicle. In any case the DMS has to
ensure that the access to the two different objects (customer, vehicle) is treated as a transaction, i.e. it
is either completely successful or there is a rollback.

3.4.6 Getting the details of a customer/vehicle data set

In order to get detail information about a selected customer ISPA calls the method getCustomerDe-
tails and sends a message with the structure of Figure 46. Mostly the method is called after a sear-
chCustomer and together with a changeCustomer call (section 3.4.8). In these cases a single custom-
er number is given.
ISPA will overwrite all customer data in the ISPA database with the data retrieved from getCustomer-
DetailsResponse.
Some dealers use the software component Aftersales Manager, which is an optional component to
ISPA available from soft-eng. The Aftersales Manager uses lists of customers to create aftersales
campaigns. To get the details of customers ISPA calls the getCustomerDetails method and
passes a list of customer numbers to the DMS. The DMS returns a list of customer details for each
customer number given (Figure 10).
If a customer is blocked or marked for deletion by the DMS, it will be returned anyway (in opposition to
the search result, see section 3.4.5). If the Aftersales Manager is used, the deletion flag shall be de-
fined as a flexible field. So ISPA gets the information about the deletion status. If a customer is physi-
cally deleted in the DMS, an error is returned.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 35
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 10: Sequence diagram to get the customer details

Technical details for getCustomerDetail are explained in 4.2.3.

3.4.7 Add customer/vehicle

A new customer/vehicle data set is added to the DMS
• when the ISPA user adds a customer/vehicle in the Appointment scheduler, tab Update cus-
tomer / vehicles
• when the user creates an order and the user does not yet exist in the DMS.
From the view of the DMS, ISPA adds the customer/vehicle through the method addCustomer
(Figure 48). The prerequisite is that all mandatory fields are filled. this is checked by ISPA. The DMS
returns the customer number via the method addCustomerResponse (Figure 49). A new vehicle for
an existing customer can also be created by calling changeCustomer with an existing customer
number and a VIN that does not yet exist in the DMS. In this case the new vehicle is attached to the
customer number that was sent in the request.
Immediately after that the method changeCustomer is called. This enforces that the data in DMS and
ISPA are absolutely consistent, including the customer number.
It is possible that the service case has been created with incomplete customer data. In this special
case a customer is created in ISPA but not yet in the DMS. For example at the beginning of an ap-
pointment the service advisor only knows the name, the telephone number and the registration num-
ber of the vehicle. This information is not enough for the DMS because several mandatory fields have
not yet a value. Nevertheless the ISPA user has to proceed to schedule the appointment. Before the
order is created the ISPA user has to complete all mandatory fields.
From LF2 on a customer may be marked as a passing customer. A passing customer will be sent as
part of the order (method storeNewOrderBase). Therefore addCustomer is only called when a
customer is a regular customer, not a passing one.
ISPA Light will also allow storeNewOrderBase without preceding addCustomer or changeCustomer.
Therefore, updates to vehicle information (“stateInformation”, e.g. mileage) have to be implemented in
not only in addCustomer/changeCustomer, but also inside storeNewOrderBase.

Sequence diagram

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 36
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 11 Sequence diagram addCustomer

Technical overview over addCustomer is given in 4.2.4.

Use Cases for addCustomer:

- VIN that does not yet exist:
1. Create new customer
2. Create new vehicle
3. Make the new customer owner of the new vehicle
- VIN that already exists:
1. Create new customer
2. Make the new customer owner of the existing vehicle
3. If possible: Store a “previous owner” link between the vehicle and the previous owner

3.4.8 Change customer/vehicle

The ISPA user may change this data
• when he maintains customer/vehicle data
• when the user has selected a customer/vehicle during the creation of a service case
• when he selects a service case in the appointment scheduler and selects then the menu item
Change customer/vehicle
• before creating an order base and not all mandatory fields of the customer/vehicle data are
filled.
In each of these cases the change is triggered by confirming the window Customer/vehicle data.
Before a changeCustomer request is send to the DMS, ISPA calls getCustomerDetails to retrieve the
latest set of a customer’s data. These data can then be changed by the user and send back to the
DMS via changeCustomer. Current key data are used to update the vehicle details.
There are two instances where ISPA may want to change customer details and hence send a get-
CustomerDetails request to ensure data consistency:
• Each time the customer/vehicle data is displayed in ISPA
• Before an order base is transferred to the DMS

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 37
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

There is no lock model implemented. If two users load the same customer at the same time and then
change the data, the user who makes the changes later overwrites the first changes. The reason is
that it seems not highly probable that two users access the same vehicle record at the same time for
writing while a locking concept would raise concerns in case a lock is not released correctly.
From LF2 on a customer may be marked as a passing customer. A passing customer will be send as
part of an order (storeNewOrderBase). Therefore in this case the method changeCustomer is not
called.

Sequence diagram

Figure 12: Sequence diagram changeCustomer

Technical method description for changeCustomer is presented in 4.2.5.

3.4.8.1 Usage
Change Customer is used to…
• changes the core data for customer and vehicle and/or
• changes the ownership relation between customer and vehicle and/or
• adds a new vehicle and attaches it to an existing customer

3.4.8.2 Usecases
VIN that does not yet exist:
1. Change customer core data
2. Create new vehicle
3. Make the existing customer owner of the new vehicle
VIN that already exists:
1. Change customer core data
2. If the vehicle is already somehow associated to
the customer: Change vehicle core data
3. If not: Make the customer owner of the vehicle and - if possible -:
Store a “previous owner” link between the vehicle and the previous owner

3.4.8.3 Change of Vehicle Ownership

If the customer does not own the vehicle, he is being made the owner (if the DMS supports a relation-
ship “former owner” or has a transaction log, the change of ownership should be recorded there).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 38
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

It is also the vehicle to be connected to several different custoacceptable?? to add the customer as an
additional “user” to the vehicle, if the DMS allows mers.
• ISPA Client checks with a searchCustomer if the customer owns the vehicle before sending
changeCustomer and issues a warning if a change of ownership is to take place.
• If the VIN does not yet exist, create a new vehicle and link it to the existing customer.

3.5 Work items and parts

3.5.1 Work items list

This section explains the components and the structure of the work items list. For the DMS interface
implementation it is important to understand the structure well because it is part of the order base
which ISPA sends to the DMS to create an order. The structure of the order base and how the work
items list is transmitted is explained in section 3.6.3.
The ISPA user composes the work items list during the process phases Appointment scheduling,
Consultation preparation and service consultation. A work items list consists of items of different types:
• Flat rate unit (FRU): a labor, either from the BMW central KSD or from the local DMS, consist-
ing of a number, a name and a number of time units (at BMW a unit is 5 minutes)
• Service repair packages (SRPs): a package, either from the BMW central KSD or from the lo-
cal DMS, consisting of a FRU and one ore more parts. An SRP may have a lump sum or a
fixed price.
• Conditional based service (CBS) items: FRUs and SRPpackages (FRU and one or more
parts) which are automatically chosen by ISPA on the base of the vehicle data, e. g. change of
the brake fluid
• Labors of the workshop catalog: labors from a catalog which is stored in the ISPA database.
These labors are usually used for a rough planning, while FRUs and SRPs are used for the
detailed planning. They have no number and no price.
• Interactively created structure elements (manual packages): Used to structure jobs with indi-
vidual names
• Parts: selected from the BMW Electronic parts catalog (EPC), which contains BMW central
parts and local parts which are added in the local EPC installation, or local parts directly from
the DMS
• Items from third parties (work items and parts): Interactively created items, e. g. for tow-in ser-
vice, may have a price set by the ISPA user.
• Technical campaign information
• SRPs may have different types. A new type is the marketing SRP (section 3.5.4).
• Third party items are added (section 0).
• There are different sources for these items. When the service advisor composes the work
items list, he chooses the source and then selects the requested item from the source. Figure
13 shows the sources as they are displayed in the ISPA user interface.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 39
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Technical Campaigns

Third party item

Figure 13: Sources for work items and parts in the ISPA interface
The sources are:
• KSD: BMW central FRUs and SRPs
• Manual package: for interactively created packages
• DMS: FRUs and SRPs which are dealer individual (local) and stored in the DMS
• Technical Campaigns: Work items from technical campaigns
• ISPA repair tasks: Labors of the ISPA workshop catalogue, which is stored in the ISPA data-
base
• EPC: BMW central parts from the Electronic Parts Catalog
• Accessible by an icon only: Direct adding of items by entering the item number.
• Third party item: Direct adding of third party items (external sources)
• Wheel and tyres: Transferred as parts if a BMW part number exists; if not, they are trans-
ferred as third party items (“ISPA_SUBLET”) with a fixed price.
The work items of the different sources are shown with different background colors in the work items
list.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 40
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

ISPA repair task

2 BMW central FRUs

BMW central SRP
Local FRU

Job from CBS data with

2 FRUs and 5 SRPs included

Manual job with ISPA

3 repair tasks

Manual job with 1 central

SRP and a manual package
containing 2 central FRUs

Figure 14: Example for a complex work items list

Figure 14 shows an example of a structured work items list with eight jobs. Understanding the job
structure is important because the order base which is transmitted to the DMS reflects this order struc-
ture. The printouts of the workshop order and the invoice shall have the same structure as the work
items list.
• Job 1 consists of a single ISPA repair task that was chosen from the ISPA workshop catalog.
• Job 2 and 3 are single BMW central flat rate units that were taken from KSD.
• Job 4 consists of a BMW central service repair package, selected from KSD, too. An SRP is a
job with one structure level, since it consists of a FRU and one or more parts.
• Job 5 represents a single local flat rate unit which was chosen from the local catalog of the
DMS (section 3.5.2).
• Job 6 was automatically created from the condition base service information which was read
in from the vehicle key. The name order basis from key data is automatically set and cannot
be changed by the user. The job consists of flat rate units and several service repair pack-
ages. Note that this job has two structure levels: the job and the SRP.
• Job 7 was created by applying the source Manual package and interactively changing the
name to Job with ISPA repair tasks. The job is structured in one level and contains two entries
of the ISPA workshop catalog.
• Job 8 is the most complex one. It consists of two substructures. One is a central SRP from
KSD, the other one is a manual package which consists of two central FRUs of KSD. The ma-
nual package was created from the source Manual package again, interactively renamed to
Manual package containing the FRUs of the job and moved under the job Job with central
FRUs and central SRP.
Items of the workshop catalogue, which is stored in the ISPA database, are labors, which have no
counterpart in the DMS. They are used for the rough planning during the appointment scheduling. In

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 41
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

the order base they are mapped to FRUs without a FRU number. Instead of the number the string
"ESTIMATE" is set.
Parts are added from the electronic parts catalog (EPC) or by directly inputting a part number in the
items catalog (section Fehler! Verweisquelle konnte nicht gefunden werden.). Parts also come as
components of SRPs. The user may position a part in the top level as a job for its own or as part of a
job respectively a manual package.
The job structure is restricted to two levels, as shown in Figure 14. A deeper job structure is not sup-
ported neither by the ISPA user interface nor by the XML scheme.
See section 3.6.3 how the structure and the positions of the items catalog are transferred to the DMS
during the order creation and how the shall be managed within the DMS.

3.5.2 Local SRPs und FRUs from the DMS

3.5.2.1 General

ISPA user interface

The ISPA user opens the window DMS catalogue (Figure 15) from the window Define items and ve-
hicle data when he selects the source Local SRPs/FRUs. There are two tabs to select local SRPs and
local FRUs.

Figure 15: Window DMS catalogue in ISPA

ISPA sends the VIN to the DMS to identify the vehicle. The DMS searches for all available and appli-
cable local SRPs and FRUs and returns a list of all groups of local SRPs respectively FRUs. The

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 42
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

search for these packages and labors shall be independent of whether the vehicle already exists in the
DMS.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 43
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.5.2.2 Adding local FRUs from the DMS

Sequence diagram

Figure 16: Adding a local FRU

List of local FRUs with getLocalFlatRateGroupList

From the window DMS Catalogue the user gets the list of local FRUs when he selects the tab Local
FRU (Figure 15). With this selection ISPA calls the method getLocalFlatRateGroupList (Figure
52).
ISPA expects that the local FRUs are organized in FRU groups and that the groups which are applica-
ble to a vehicle are identifiable by the VIN. ISPA requests the FRU groups through the method get-
LocalFlatRateGroupList(), see technical details in 4.2.6.
The user then selects one of the FRU groups in the window DMS catalogue. ISPA triggers the DMS to
give back a list of FRUs of this group that is applicable to the specified vehicle (getLocalFlatRate-
Group()).
Finally the ISPA user selects a FRU and adds it to the work items catalog. Method getLocalFla-
tRateDetails is technically presented in 4.2.8.

3.5.2.3 Adding local SRPs from the DMS

Sequence diagram

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 44
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 17: Adding a local SRP

Used methods
• Method getLocalSRPGroupList
• Method getLocalSRPGroup
• Method getLocalSRPDetails
SRP groups are displayed on the left side of the DMS catalogue window. When the user selects a
local SRP in order to add it to the items catalogue of the service case, ISPA requests the details of the
local SRP. SRP is identified by its number. All parameters and response details are shown in 4.2.11.

3.5.3 Direct adding of local parts

Local parts can only be added by entering the part number directly in ISPA Client; there is no cata-
logue of local parts like there is for local packages and flat rate units.
ISPA transfers the part number to the DMS. The DMS delivers the part details back to ISPA.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 45
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Input part number

directly

Figure 18: Input a part by the part number directly in the window Entering services and vehicle
data
When the user decides to insert a local part the DMS has to ensure that only local part numbers are
accepted by the DMS. When a central part number is transferred to the DMS, the DMS has to return
an error (e. g. REJECT - local part not known). This restriction is imposed by the BMW program PPQ
9-1 and PPQ 9-2, for central part numbers may be searched and added only via the electronic parts
catalog (EPC).

Sequence diagram

Figure 19: Sequence diagram add part by direct input of the part number

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 46
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

It is also possible to manually enter local FRU numbers in ISPA Client. Packages can only be entered
via selection from the catalogue.

Figure 20: Direct adding of a FRU

The methods getLocalSRPDetails and getLocalSRPDetailsResponse have been introduced
in section 3.5.2.2. "Local" in the name of the method refers to that the request is sent to the DMS .
If the FRU exists, ISPA inserts the FRU into the work items list of the service case. If not, an error
element is returned.
For BMW central FRUs there is an alternative function, too, to enter the number of the FRU directly. In
this alternative the KSD is opened and the page with the requested FRU is opened.

3.5.4 Price types and price calculation

ISPA displays prices for the elements of the work items list and parts list. Since the DMS is the source
of the price data, the prices are requested from the DMS. Regular prices (except order specific prices,
prices of marketing SRPs and prices of third party items) are not stored within ISPA and are always
updated in real-time from the DMS.
Table 5 lists the price types of ISPA. The order split is described in section 3.6.5. The DMS has some
tasks to perform to prepare the requested price information.
In LF2 one more mandatory element is transmitted from the DMS to ISPA by the method getPri-
ceInformationResponse: the full retail gross price. The price is subject to an order split displayed
in a new column in the ISPA window Entering services and vehicle data.
The service advisor can manually change the customer specific price that is sent to the DMS (section
3.5.5.1). This will allow the ISPA user to manually give discount to customers by changing the price
retrieved from the DMS during getPriceInformation.
Marketing SRPs (section 3.5.5.2) and third party items (section 3.5.5.3) may have an offer specific
price assigned. With marketing SRPs, either an offer specific price or an offer specific discount is set.
Table 5: List of price types

Name in the XML scheme element Content Comment

ISPA GUI name
List price retailGrossPrice Retail gross price: the dealer's Source = DMS
(gross) standard retail gross price (catalog No subject to order split
price)
List price retailPrice Retail net price: the dealer's stan- Master = DMS
(net) dard retail net price (catalog price) No subject to order split
Customer grossPrice Customer specific gross price Master = DMS

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 47
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Name in the XML scheme element Content Comment

ISPA GUI name
specific price including all taxes with the cus- Subject to order split
(gross) tomer specific discount applied
Customer customerSpecificPrice Customer specific net price with Master = DMS
specific price the customer specific discount Subject to order split
(net) applied
– customerSpecificDis- Customer specific discount: dis- Master = DMS
count count percentage defined for this not displayed in ISPA
customer in the DMS
– taxRate Tax Rate: percentage of tax. May Master = DMS
be specific to the customer or the not displayed in ISPA
vehicle type.
Discount offerSpecificPrice Fixed net price Master = ISPA
- for marketing SRPs
- third party items
- customer specific price set by
the service advisor
Discount offerSpecificGros- Fixed gross price Master = ISPA
sPrice - third party items
- customer specific price set by
the service advisor
Discount offerSpecificDiscount Fixed discount percentage from Master = ISPA
the customer specific net price
(set by the service advisor)
Discount offerSpecificGrossDis- Fixed discount percentage from Master = ISPA
count the customer specific gross price

In a price request, for each item the element group groupOfferPriceEntry is transmitted to the
DMS (Figure 129), technically described in 4.5.9.
A price respectively a discount in a price request is optional. One of a choice of four elements can
occur. If it is present the flag element <hasFixedPrice> also must exist and have the value true.
The flag is explicitly set by the user in the ISPA user interface.
In a response on a price request, for each item the element group groupPriceEntry is returned
from the DMS (Figure 130), see 4.5.10 for technical feature description.
If a package has a price as a lump sum, the element <offerSpecificPrice> exists for the flat
rates and the parts that are contained in the package. The value is 0.0. This indicates that no explicit
FRU prices respectively parts prices are defined for a lump sum package.

Customer specific prices

Depending on the discount level of the customer the prices for SRPs -, flat rate units and parts are
reduced by the DMS and transmitted to ISPA. These are called customer specific prices. In order to
get the customer specific discounted net prices from the DMS, the customer ID or the VIN has to be
transmitted to the DMS. Otherwise the standard retail prices (list prices) are sent back to ISPA. If there
is no SRP lump sum, then the discounted prices of its components (flat rate units and parts) are indi-
cated. In this case the SRP discount results from the sum of its discounted component prices. Howev-
er, if a discounted SRP lump sum is present, the prices of its components are not indicated.
If an offer specific discount was set in the price request it will be returned by the response in element
<customerSpecificDiscount> or <offerSpecificGrossDiscount>. If an error occurs an
error element is given.

Rules for the price information

The calculation scheme covers the following price levels and percentages.
Rules for the price calculation:

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 48
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• Some prices in Table 5 are marked by “Master = DMS”. These prices can only be read by
ISPA but cannot be changed. But they can be overridden for a specific offer.
• The customer specific price may include a quantity discount that can be part of the customer
specific discount or already be included in a quantity specific retail price.
• Since prices may depend on the quantity, they have to be recalculated each time the quantity
of a SRP, a FRU or a part is changed in ISPA.
• Prices for flat rates or parts are communicated as price per unit.
• If an order split is given (see section 3.5.7), the DMS calculates the different prices in the
same manner as without an order split. In comparison with a non order split the DMS only de-
livers prices, which are assigned to the customer. In other words, only the price rates of the
customer have to be sent back towards the ISPA system.
• An SRP discounted price results from the sum of its discounted components (flat rate units
and parts) if there is no lump sum.
• The DMS computes always the total price (price * quantity) per item (SRP, AW and/or part)
and delivers the result to ISPA. Every change of quantity for a certain item in ISPA leads to a
new price calculation within the DMS.
• If offer specific prices are given (absolute prices or discount percentages) these override the
DMS prices.
• Technical campaigns and work items of the ISPA workshop catalogue have no price. There-
fore the DMS is allowed to send a price these planning positions. The same rule applies if
these positions have been transferred to the DMS.
Customer specific prices require that the customer exists in the DMS. If the customer does not yet
exist in the DMS, which can occur when the customer data are still incomplete, the DMS returns the
list prices.

Dealer individual Parts, flat rates and SRPs

If the dealer exchanges certain BMW parts with dealer individual parts (DIP), ISPA displays the price
of the DIP. The exchange of the part is done within the DMS when the parts availability is checked.
Prices for dealer individual parts (e. g. oil) are sent from the DMS to ISPA, if the data fields replaced
part number and replaced part designation contain the respective values in the DMS. If a part has
been exchanged ISPA calls the method getPriceInformation for that part to ensure that the price
of the exchanged part will be displayed in ISPA.

Display of prices in ISPA

Figure 21 shows the display of prices within ISPA in the window Entering services and vehicle data.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 49
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Price information from the DMS

Figure 21: Display of prices in ISPA

3.5.5 Work items and parts with fixed price

The price information has to be always consistent within the service process (display in ISPA, order
and invoice). The DMS has to ensure that the consistency is given especially for fixed prices, market-
ing SRPs and third party items that are documented in this section.

3.5.5.1 Fixed prices and discounts set by the service advisor

The ISPA user has the possibility to set offer specific prices explicitly that override the DMS price set-
ting. This feature applies to the item types:
• FRUs and SRPs from KSD
• local FRUs and SRPs
• parts from the EPC
• local parts
The price can be set in one of the following ways:
• a fixed net price (value in <customerSpecificPrice>)
• a fixed gross price (value in <customerSpecificGrossPrice>)
• a discount from the customer specific net price (value in <customerSpecificDiscount>)
• a discount from the customer specific gross price (value in <customerSpeficGrossDis-
count>)
The ISPA user interface contains a discount column in the window Entering services and vehicle data.
Here he inputs either a net or a gross value of the offer specific price. In a context menu the user de-
fines whether the input is an absolute or a relative (%) value.
In each case the element <isFixedPrice> exists in a price request and has the value true.
Often a first automatic price request is done when an item is added to the work items list. The prices
as calculated by the DMS are returned and displayed in ISPA. In a second step the user sets custom-
er specific prices. A second price request contains the information about the offer specific price.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 50
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The DMS calculates all return prices from the offer specific price data given. For example, if a discount
from the customer specific net price is defined, the DMS calculates the customer specific net price and
gross price. The DMS returns the element again <isFixedPrice> with the value true.
If the DMS does not allow that the ISPA user sets offer specific prices the DMS will return an error as
part of the response. The restriction may exist because
• in no case a service advisor has the right to set prices or
• only certain service advisors have the right to set prices
• the policies of a market or a DMS or do not allow to set prices outside of the DMS

3.5.5.2 Marketing SRPs

ISPA LF2 introduces so-called Marketing SRPs. These are regular SRPs from the KSD as far as the
structure and the content are concerned. The price, however, is reduced. The reduction is
• either a fixed reduced price
• or a fixed discount percentage from the dealer's net catalog price
The fixed reduced price is stored in the KSD, as well as the discount percentage. In the case of a dis-
count percentage the KSD gets the dealer's net catalog price via a KSD-DMS interface and calculates
the reduced price. So, in both cases the KSD transfers the marketing SRP price to ISPA.
If the service advisor adds a marketing SRP to the work items list it is automatically marked in ISPA
that is has a fixed price. In a price request to the DMS, a marketing SRP is represented by:
• the SRP type in the element <packageType>
• a flag <isFixedPrice> set to yes
• one of the elements that specify an offer specific price exists
ISPA hands over to the DMS these new elements together with the existing information of an SRP.
The DMS has to store these elements together with the SRP information.
Note: The same structure will be used in later delivery stages for Technical Campaign Packages.
They will be a part of the warranty process.
Note: Also for FRUs new elements for FRU type and fixed price flag are defined. The type element is
not needed for FRUs, however, and has been removed again in version 3.1.1.
The DMS does not calculate the customer specific price by itself, rather it sets the given net price to
the customer specific net price. The DMS calculates the customer specific gross price from the given
offer specific net price. The DMS returns the customer specific prices and – as with standard SRPs
respectively FRU – the catalog prices. If an SRP contains parts the calculation is applied the same
way.

3.5.5.3 Work items and parts from third parties

Often the service advisor has to add items to the work items list which come from third parties. For
example the vehicle is towed in by a breakdown service or a standard part is bought from a spare
parts shop because it is currently not in stock at the dealer. These items can be added as a third party
item. The service advisor inputs the description, for example "Towed in by Joes Day'n'Nite Service".
Optionally a net price or gross can be given.
When a third party item is transferred to the DMS during the order creation, it is mapped to a flat rate
unit that comes within the structure of a flat rate unit. A customer specific price is set; either as a net
price (element <customerSpecificPrice>) or as a gross price (element <customerSpecific-
GrossPrice>) (see section 3.5.4). The element <isFixedPrice> is present and has the content
true.
The DMS identifies a third party item by the flat rate number "ISPA_SUBLET". The description of the
flat rate may be evaluated as a text field by the DMS.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 51
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

It is in the decision of the DMS to

• take the price without checking it as a fixed customer specific price or to
• calculate the price itself and replace the suggested ISPA price.
The workshop order and invoice shall print a third party with the given description.
The ISPA user may assign a net or gross price to a third party item. This price is transferred to the
DMS as an offer specific net price. It is up to the policies of the DMS whether it
• takes this price without any internal check or
• to ignore the price and calculate a price applying the DMS internal calculation scheme

3.5.6 Request for price information

Sequence diagram price information

Figure 22: Sequence diagram price information

For requesting price information see getPriceInformation().

3.5.7 Specify billing arrangements (order split)

The price information has to be always consistent within the service process (display in ISPA,
order and invoices). The DMS has to ensure that the consistency is given especially for an or-
der split that is documented in this section.
The service advisor my assign an item (FRU, SRP, part) to one or more cost units. Typical cost units
are:
• the BMW AG for warranty cases
• the BMW AG for Service Inclusive service cases
• the dealer for generousness
• a leasing company
• an insurance company
The assignment may be totally (100 % to the BMW AG) or partially (e. g. 50 % to the customer and 50
% to the leasing company).
By default the customer (the keeper of the vehicle) pays the full price.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 52
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 23 shows the window Entering services and vehicle data in the ISPA user interface where the
service advisor defines the billing arrangements.

Customer Prices Cost units

Figure 23: Items catalogue with order split in ISPA

The percentage information is part of the method getPriceInformation. A price needs to be re-
calculated by a DMS if the percentage value of a SRP, labor or part is changed in ISPA. The element
orderSplitPercentage percentage is not present for an item or has the value 100. The sum of all
percentage values must be 100. This is checked by ISPA. If the customer pays less than 100 %, the
element orderSplitPercentage exists and contains the value of the percentage.
Note that an order split is possible on different levels of the job hierarchy. If ISPA defines an order split
is defined on a deeper level, it will not define an order split at a higher level in the same job. This is
ensured by ISPA. By this way inconsistent order split information is avoided.
The prices that are displayed in the user interface are always customer specific prices. So the DMS
only has to calculate these, not the prices of the other cost units.
When an order is creates, the order split information is part of the order base and is also transferred to
the DMS as part of the order base. All cost units must exist as customers in the DMS. Details are dis-
cussed in section 3.6.5.
Display of prices at an order split
If an order split is done for a position of for a job, ISPA shall display for each position respectively job:
• the list price
• the customer specific gross price
• the customer specific net price
The customer is the keeper of a vehicle. If the customer has not to pay the full price, the customer
specific prices are the reduced prices according to the order split percentage, while the list price al-
ways is the full price. In the method getPriceInformation the element orderSplitPercentage is set the
percentage which the customer has to pay.
Figure 23 shows an example. The work items list consists of four jobs with one FRU position each.
The first job is paid by the customer itself. The order split percentage is 100. The second job is paid by
warranty. The order split percentage is 0. The third job is paid by the dealer, The order split percen-
tage is 0, too. The fourth job is paid by the customer with 40 %, the rest is paid by the leasing compa-
ny. The order split percentage is 40 %.
When ISPA requests the prices from the DMS, ISPA transmits only the customer specific order split
percentage. Only when the order is created ISPA tells the DMS the cost centers (section 3.5.7).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 53
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Cost center with several accounts

In some markets a debtor has more than one account. Often the dealer itself is a cost unit with several
accounts. In this case the order split has not only to define the cost units but also the accounts, which
is optional. This feature is implemented in some DMS. ISPA supports this feature in the delivery stage
2. The administrator defines accounts to a cost center in the system console. If present, the ISPA user
assigns an order split not only to a cost center but also to an account. Section 3.6.5 describes how this
information is transferred to the DMS when the order is created.

3.5.8 Check parts availability

3.5.8.1 Process description

The service advisor ensures a reliable vehcile return date by by knowing the availability of the parts.
So he can communicate whether the necessary parts for the service case are in stock or have to be
ordered first. He even will be able to see in ISPA whether each part is on stock in the branch he is
working at (his home branch) or at another branch of the dealer.
If the dealer exchanges BMW parts by dealer individual parts (DIP), the exchange is performed within
the scope of the availability check. The stock of the DIPs is displayed in ISPA. If a part has been ex-
changed ISPA calls the method getPriceInformation for that part to ensure that the price of the
exchanged part will be displayed in ISPA.
When a part is added to the items catalog or the quantity of a part is changed ISPA requests the
availability of that part from the DMS. The DMS checks the number on stock and returns the result to
ISPA (Figure 24).
If a part is not known in the dealer parts database, the DMS returns
• that the number on stock is 0 and
• an error that the part is not known in the dealer database
The part may exist, however, in the central BMW parts database. In this case the list prices will be
shown. This seeming contradiction is presently accepted.

3.5.8.2 Sequence Diagram

Figure 24: Sequence diagram check parts availability

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 54
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

In order to check the parts stock ISPA sends a request with the structure given in 4.2.14 (check-
PartsAvailability).

3.5.8.3 Dealer with several branches

If a dealer owns several branches the service advisor gets the possibility to see the part availability of
all branches of the dealer. The number of parts available in his own branch is stored in the element
partsAvailability. The number of the other branches is stored in the element partAvailabi-
lityBranch.
The number of parts is calculated by the DMS in the following way. Consider a dealer with three
branches A, B, and C (Figure 25). Each branch has one or more storage places (A1, A2 for branch A).
The ISPA user is associated with branch A. Branch A has 5 parts in stock, two of them in A1, three in
A2. The DMS sums up the parts of the storage place and store "5" in the element numberOnStock,
subelement of partsAvailability.

Dealer organization Dealer

partAvailabilityBranch

partsAvailybility

5 4 6
Branch level Branch A Branch B Branch C

2 3 4 1 2 3
Storage Storage Storage Storage Storage Storage Storage
level Place A1 Place A2 Place B1 Place C1 Place C2 Place C3

The branch of the ISPA user is A.

Figure 25: Dealer with branches and storage places
For the other branches B and C, the DMS returns the branch's name and the number of parts in stock
in each branch (sum of the storage places) as a list of <partAvailabilityBranch> elements. The
rendering in ISPA is shown in Figure 26.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 55
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Number of parts available in the

ISPA users‘s branch

Number of parts available in branch FIL1

Number of parts available in branch FIL2

Figure 26: Display of the parts availability in ISPA

3.5.9 Parts ordering/reservation: Blocking items in DMS (LF4)

During the order lifecycle (creation – part reservation – part ordering) related work items (parts and
flatrateUnits) must be blocked by DMS. This must be kept in mind when sending part and/or FRU data
to ISPA, every part and FRU has a new optional blockedWithReason-element to indicate blocked
states:

The element blockedWithReason should only be sent if an item is blocked by DMS. Blocked items
are especially treated in ISPA’s new synchronization process introduced with the order extension in LF
4. See type description for parts in 4.3.19 and for FRUs in 4.3.22.
So far the following valid reasons for blocking are known. Other reasons may be defined by the DMS
(they have to be documented in the Release Notes):
• Blocked Part because of a connected parts order that cannot be automatically cancelled
• Blocked Part because it has already been issued to a mechanic and been used for repair
• Blocked FRU because a mechanic has already clocked on to this position
If a block category is valid for a part or FRU, the DMS must give a textual description to ISPA explain-
ing the blocked reason. This description should be in the language indicated by the <userInformation>
header in the request.
Note: Part reservations are NOT a valid reason for blocking a part or FRU. They should be automati-
cally released. The DMS should also make sure a storeNewOrderBase does not mark all parts as
“picked”, so that all of them become immediately blocked.

3.5.9.1 Inheriting blocked states of parts and FRUs

Regardless only parts and FRUs can be blocked - this affects parent packages, jobs and orders for
ISPA: if a job part item is blocked, ISPA will mark the whole job as blocked to indicate synchronisation
need to ISPA user in the ISPA user interface.
The DMS has no need to care about this; blocked states are not extended to other item types by intro-
ducing new flags in LF4.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 56
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.6 Orders

3.6.1 General
At the end of the process Service reception the service case contains the complete work items list.
The service advisor now creates an order base and transfers it to the DMS. The order base contains
all information that is needed to create an order. The DMS checks the order base and, if no errors
occurre, creates the order.
The data structure of the order base is transferred by the method storeNewOrderBase. The DMS
answers by calling the method storeNewOrderBaseResponse. The data structure and the expected
interpretation by the DMS are described in this section.

3.6.2 Transaction Context and new DMS timestamp updating (LF4)

A new and very important concept is the introduction of a lastChangedDMSTimestamp for ISPA on
DMS-side. This is needed to implement new order extensions and improve and extend order item
synchronization between ISPA and DMS.
Every time DMS adjusts, creates or modifies order data (base and header), triggered by internal or
external method calls, the timestamp must be updated in DMS.
External ISPA Triggers are:
• storeNewOrderBase
• addJob
• cancelJob
• updateOrderHeader
• releaseOrder
DMS internal triggers are:
• DMS user actions:
• DMS order state transitions (e.g. sync status),
• DMS internal data modifications
• DMS internal updated to prices connected to items used in parts or FRUs
• Other systems connected to DMS altering DMS order base or header data (cascade effect)
Every time such a triggering event occurs, DMS must update mentioned new timestamp lastChan-
gedDMStimestamp to indicate ISPA changes to order data base or header. At least, this change has
to be done by DMS in transactional context: if a transaction in DMS fails and is rolled back, the time-
stamp is not updated and restored. Otherwise if a DMS order transaction passes successfully, the
timestamp is modified inside of the transaction at the end.
ISPA expects the timestamp lastChangedDMStimestamp in many responses to compare it to in-
ternal timestamps and therefore recognize differing order data in DMS easily. This concept reduces
time and effort for DMS and ISPA because sometimes no additional getOrderBase requests are ne-
cessary to determine order’s sync state. If timestamps do not differ, ISPA knows that DMS order and
ISPA order are the same on both systems.

3.6.3 Order base

3.6.3.1 Structure
Aim: Transparency of the invoice: Invoice, order and ISPA order structure should be as similar as
possible.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 57
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• When return an order that was created from ISPA, retain the job structure (i.e. job numbers
should be the same). If necessary, store the job number in a separate column.
• Ideally the user in the DMS should recognize the structure. At least it should not be destroyed
by editing the order in the DMS (adding/deleting/changing lines).
• Orders created directly in the DMS should have a meaningful structure, too. If there is no fur-
ther structure of the orders in the DMS, transfer one big job that contains all labor units and
parts of the job.
See typeOrderBase and groupOrderHeader.

Order Header
Order header contains information related to the order, important fields are:
• DMS sync status
• Dealer details
• GUID
• Guid number
• Vehicle
• Service advisor information
• Return and completion date
• Parking position

Job order positions

• Packages (SRPs) from KSD
• Warranty repair packages (GRP) from KSD
• Marketing repair packages (MRP) from KSD
• Parts from ETK/EPC
• Local Parts (entered manually)
• Local DMS packages (from catalogue or entered manually)
• Local DMS FRUs (from catalogue or entered manually)
• Technical Campaigns
• ISPA repair tasks = estimate positions
• Sublet tasks = placeholder for external work

3.6.3.2 Passing customer

If a customer is marked as a passing customer the flag field Passing customer of the customer data is
set to "yes" (section 3.4.1). In this case the customer does not exist in the DMS database, that is the
methods addCustomer and changeCustomer have not been called. For a passing customer, the
element <passingCustomerInformation> of type typeCustomerDetail exists and contains
the complete customer and vehicle data, see section 3.4.1 (Figure 106). The element <customer-
Number> does not exist.
The DMS uses this data for the workshop order and the invoice. The DMS need not create a customer
debtor.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 58
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.6.4 Job number issues (LF3 and LF4)

This subchapter is very important to understand job handling, identification of jobs by ID, job ID lifetime
and job package relations.

3.6.4.1 Constant job numbers

Job numbers must be constant in DMS and ISPA:
• ISPA and DMS should use same job numbers for identification. If ISPA sends a job to DMS
(e.g. storeNewOrderBase), all DMS requests in future (e.g. getOrderBase) will return the
same job with the same job number.
o Exception: New jobs added in ISPA are sent to DMS by addJob: if DMS answers with
an alternate job number, this ID is overwritten in ISPA. Afterwards modification of the
job number is NOT allowed. This is crucial for workflow and clean state transitions for
orders
• If jobs are deleted in ISPA or DMS, no “job number shift” is performed: if there are 3 jobs (100,
101 and 102) and job 101 is deleted, job 102 keeps its job number. Number gaps are allowed
and not purged
• DMS with job number limits have to provide alternate job number constructs (e.g. new DMS
job attributes) to keep track of ISPA job number. If so, all requests and responses carrying job
numbers must refer to that alternate job number

3.6.4.2 Valid job number gaps and no reusage of job number

If a job number is used once in an order, it cannot be reused after removing the old job: job number
gaps are valid in an order and ISPA and DMS are not allowed to fill job number gaps.

3.6.4.3 Fallback option for limited job and package representations

ISPA supports and works with a hierarchy depth of 4 for its order and order items:
• Order (depth level 1)
o Job (depth level 2)
 Parts (depth level 3)
 FlatrateUnits (depth level 3)
 Packages (depth level 3)
• Parts (depth level 4)
• FlatrateUnits (depth level 4)
This hierarchy depth represents the possible maximum sent by the interface, is it is NOT the common
use case. In general only orders with simple jobs (with 1 package or parts/FRUs are sent). These le-
vels can be passed to DMS (storeNewOrderBase, addJob) and should be returned by DMS if DMS
supports the same level depth. If not (and only if not), a fallback must be used described below.2

Fallback for DMS supporting less than 4 depth levels

If DMS cannot represent more than one packacke in one job, jobs with 2 packages can be sent back
from DMS to ISPA flattening job structure.
Conditions

2Some DMS uses job rows with menuCodes to connect ISPA job or packages to DMS job row items.
Therefore these DMS cannot support hierarchy depth levels like ISPA and must alter received and
sent order base (bottleneck effect)
GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011
BMW Group Page 59
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• DMS does not support more than one package in one job
• DMS does not support sending one job with one package and a single separated flatrateU-
nit/part on the same depth level (e.g. see depth level 3 above).
Result:
• DMS merges additional packages into first package and discards all other package headers,
items of discarded packages (parts, flatrateUnits) are added to the first package. If there is a
subpackage (see depth level 4 above), its contents are put into the first package in the same
manner, subpackage’s header is discarded too.
• The header of the first package survives and is not altered.

This behavior ensures correct work of introduced synchronization dialog agent in ISPA even with li-
mited hierarchy in connected DMS. Be aware that this is a fallback option and should be only imple-
mented for DMS with mentioned limitations.

3.6.4.4 Jobs in order’s jobList

The data element job list is part of the attribute service information of the order base (see figure in
3.6.3.1).
Well structured, transparent invoices lead to increasing customer understanding and trust in the ser-
vice. The structure has to appear in the order as well as in the invoice. When the order base is
changed during the order fulfilment (order extension, exchange of items), therefore the maintenance of
the job structure within the DMS is crucial.
The job list can have a rather complex structure. Therefore the DMS interface implementer shall care-
fully analyze the possible structure variants. See section 3.5.1 for how the work items list is composed
in the ISPA user interface.
Detailed technical description can be found in 4.3.17.

3.6.4.5 Default Jobs and contained items

If DMS uses a default job (e.g. with DMS reserved job number 99) for identifying default items, these
items can be modified (added/deleted) by ISPA using addJob/cancelJob in the same way other items
can be altered. For example deleting this job 99 using ISPA and calling cancelJob(99) should trig-
ger DMS to remove all default positions.
Summary: DMS is responsible to let ISPA access default jobs in the same way as other jobs.
See cancelJob (4.2.23) for technical information.

3.6.4.6 Enhancement for SRP Monitoring with Version 3.1.3

If a dealer belongs to a market that has agreed to deliver prices to BMW, the customer specific price
information is manditory. All packages, flat rate positions, as well as parts need to state the net price of
the dealer as well as the related currency in the complex datatype CustomerSpecificPrice. This price
information has to be reached on from ISPA to FBM.
See 4.5.12 for structure details of typeDiscountedPrice.

3.6.5 Order split information

Each work item of the work item list e may be assigned to up to 15 cost centers. See Figure 23 for a
screenshot of ISPA. The item may be assigned to one cost center with a given percentage 100 % or to
several cost centers to a given percentage. This information is stored in the element orderSplit,
which is part of the element group groupJobRow (Figure 77, see chapter 4.5.13).
The element group groupJobRow appears within

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 60
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• Job
• part
• flat rate unit
• package
For each cost unit one <orderSplit> element is given. If no orderSplit element exist the DMS
sets the default cost unit, that is the customer with 100 % of the costs. ISPA assures that the sum of
all percentages of all orderSplit elements if one item is 100 %.
Note that an order split is possible on different levels of the job hierarchy. If ISPA defines an order split
on a deeper level, it will not define an order split at a higher level in the same job. This is ensured by
ISPA. By this way inconsistent order split information is avoided.
The content of <costUnit> is displayed in the ISPA user interface. The customer number must be a
valid customer number in the DMS.
The elements lockFlag and rowNumber are currently not used. They are reserved for future use.
Cost center with several accounts
In some markets a debtor has more than one account. Often the dealer itself is a cost unit with several
accounts. In this case the order split has not only to define the cost units but also the accounts, which
is optional. This feature is implemented in some DMS. ISPA supports this feature in the delivery stage
2. The administrator defines accounts to a cost center in the system console. If present, the ISPA user
assigns an order split not only to a cost center but also to an account.
ISPA configures the list of accounts to the debtor an transmits the chosen account in the elements
<accountNumber> and <accountName>. It is up to the DMS to use this feature. If it used the DMS
treats the account information as it needs.

3.6.6 Structure of the customer statement

Customer statement means a combination of qualified statement (based on VFC) and/or original
statement.
The aim is to record the statement made by the customer based on a structured fault pattern catalog.
Here the originals statement of the customer is qualified by the selection of given expressions as well
as of a free text field for the original statement of the customer.
The qualified statement customer is recorded as early as possible in the vehicle service case. At this
point, it is important to record the original observation of the customer. Changes to a recorded state-
ment are no longer possible when the order is created in the DMS. Thus the statement made on cus-
tomer contact cannot be falsified later.

Elements
• Original Statement: What the customer said
(“I heard strange noises when breaking”)
• Qualified Statement (VFC): Structured Questionnaire consisting of VFC.
• Repeated Repair flag: If true, this is a repeated repair

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 61
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 27: The customer statement editor in ISPA (VFC based)

The qualified statement and original statement customer is defined on the job level (Figure 111). An
original statement may exist without a qualified statement and vice versa. The statement is printed on
the workshop order (and it is recommended on the invoice). Section 3.6.16.2 describes how it shall be
rendered on the printout.
Every job has one mandatory <customerStatement> element (technical structure in chapter 4.3.21)
with qualifiedStatement and originalStatement. The general rule that child elements exist only when
they have content also applies for the customer statement.
The qualified/original statement is a data structure which is composed in VFC dialog (Figure 27).
The qualified/original statements are stored by ISPA. DMS has to ensure to track all fields in type cus-
tomerStatement.
See ISPA CR VFC and for more details.
• The DMS must store the qualified statement either as an XML structure or as a string that is
created from the XML elements. The user should have the possibility to see an existing quali-
fied statement inside the DMS when working with the order.
• If ISPA passes an original statement to DMS, DMS has to map to its data structure (use the
existing customer complaint / customer statement text field). If mapping is not possible, the
DMS must use an additional field for storage.
• Original and qualified statement must be printed by DMS (described in 3.6.16.2)
The technician in the workshop has the possibility to add a qualified workshop statement to a job. A
software component will be available to input the statement. The software is not part of ISPA and will
be launched by the DMS, see section 3.7).

3.6.7 Order extension (LF4)

The following picture shows the process-related exchange of order base data between ISPA and a
DMS. That enables the requested parts reservation process (step 2) and an order extension in context
of the core process service consultation (steps 5 and 7).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 62
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Appointment Consultation Service Order

Contact Invoicing ...
scheduling preparation consultation processing

Presence of customer
ISPA
Client 1 3b 4
order extension

2 5 7

parts reservation
DMS 3a 8

6
pick
DMS pick
list
Documents order list

Process steps:

1. Appointment scheduling initiated by automatic BMW TeleServices call or customer phone call
2. Pre-opening of the DMS workshop order (ISPA Client
DMS)
3a. Parts reservation and if required parts ordering
3b. Consultation preparation by checking vehicle and diagnosis data (provided by the BMW TeleServices Call)
4. Usage of the KeyReader and addition of CBS services and repair packages/ technical campaigns/ … result in a qualified
workshop order
5. Order extension (ISPA Client
DMS)
6. Order and pick list printouts
7. If required further work items and parts can be added in context of the service consultation without disturbing DMS
processes
8. Support of order processing and invoicing by the DMS

Figure 28 “To be” exchange of the order base between ISPA and DMS

It is aimed that running DMS processes are not disturbed in case of a transmission of modified or add-
ed order work items, packages and parts by ISPA. Therefore the data exchange has to comply with
rules to be considered by both systems. These rules are described in the chapter functional model.

3.6.8 General principles of the order base data exchange

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 63
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Appointment Consultation Service Order

Contact Invoicing ...
scheduling preparation consultation processing

Presence of customer
ISPA
Client 1 3b 4
order extension

2 5 7

parts reservation
DMS 3a 8
DMS
order 6
pick pick
list
Documents list

mode 1 mode 2

order extension by order extension only

complete replacement of the byaddtion of new
order content and considering work items
Principles of
predefined rules and parts
data exchange

Figure 29 Scope of the synchronisation modes

Regarding the order base data exchange there are two principles to control the extended data flow
between ISPA and a DMS:
• Sync Mode 1
• Sync Mode 2
• Sync Mode 3 (not relevant for data exchange, order is invoiced)

3.6.9 General process of the order base data exchange

The following process flow diagram shows the data exchange between both systems by considering
the previously mentioned principles.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 64
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.6.10 Sync Mode 1 – order extension by complete replacement

Because of the intention to reserve and order parts in advance the first order data transmission has to
be conducted early within the service process. The consequence is that the DMS order data and its
header information are not yet completely available in the DMS. The status regarding a complete and
a qualified workshop order is at the earliest reached after finishing the customer talk during the service
consultation supported by ISPA. Therefore there is without a doubt the necessity of at least one more
order base transmission towards the DMS.

Between the first data transmission and the one in context of the service consultation various changes
can and has to be conducted in ISPA caused by the result of the customer talk in order to complete
the order base content. Possible modifications are as follows:

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 65
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• Simple changes regarding the order header data (e. g. header information, vehicle return date,
park position, Leitzahl, service advisor (ID) conducting the service consultation and so on).

• Simple and complex changes by adding and modifying work items, parts and packages re-
garding their position within the workshop order, pricing, order split information, changed
amount and assigned q-ton customer information.

Instead of an expensive and complex line based synchronisation between both systems it is aimed to
conduct the synchronisation by a complete replacement of the content of the preopened DMS order
base. The current DMS order base data is then substituted by the recently sent one by ISPA as long
as the so called mode 1 is active. The order number remains the same one.

3.6.11 Sync Mode 2 – order extension only by addition of new

work items, parts and packages
With mode 2 the influence of ISPA on the DMS order data is reduced. From now on the ISPA user is
only allowed to add further work items, parts and packages to a DMS order until the DMS order status
invoiced is reached. A modification of already transmitted workshop positions is not allowed in order
to ensure that running DMS processes are not interrupted. The DMS takes over the master role of the
workshop order data.

3.6.12 Sync Mode 3 – DMS order is invoiced

This mode is entered with reaching synchronization status invoiced. No changes regarding work items
are allowed any more.

3.6.13 Relevant interface requests

With LF4 order extension has been introduced: ISPA can create order (storeNewOrderBase) followed
by addJob and cancelJob requests to change an order’s structure. Releasing an order is separated
using a new command (releaseOrder), afterwards only adding jobs is allowed, removing is not sup-
ported any more. If a DMS order is invoiced, no job changes can be done.
Each order header keeps track of the order’s synchronized status (<synchronizedStatus>). Status
transitions are invoked by either ISPA client (e.g. releaseOrder, storeNewOrderBase) or managed by
DMS itself. The following table show all allowed (which are also documented in type type)

DMS synch status Description Allowed calls Initiator

created Order is (pre-) opened in a releaseOrder ISPA
DMS. cancelJob
addJob
updateOrderHeader
printOrderHeader
confirmedCustomer Customer confirmed order. addJob ISPA,DMS
updateOrderHeader
printOrderHeader
workInProgress Order is clocked in. Status is addJob DMS
set either manually or auto- updateOrderHeader
matically by a connected
printOrderHeader
clocking system.
finishedWorkshop Workshop has been finished. addJob DMS
(former “checkWorkshop” has updateOrderHeader
been renamed) printOrderHeader

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 66
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Invoiced Order is invoiced. printOrderHeader DMS

updatedInvoice Order is cancelled by the printOrderHeader DMS
DMS user. resetOrderChangeFlag
Note: This status is re-
served for future use. DMS
implementing according to
this interface contract are
not required to implement
this status.
cancelled Order has been cancelled. printOrderHeader DMS
Table 1 Valid enumerations in order’s <synchronizedStatus> (LF4)
Be aware of allowed method calls in column “Allowed Calls”. For example if an order is in sync status
workInProgress, no releaseOrder-request will be sent to DMS.

3.6.14 Values for Order Status (synchronizedStatus)

These states are used in the state diagram which represents sync status transitions in delivery state 4
(LF4):

All job actions This mode allows adding new jobs to DMS order only. Readonly Access.
available.

<releaseOrder>

<cancelJob>

<addJob> <resetOrder
ChangeFlag>
<updateOrderHeader>

<printOrderBase>

Sync Mode 1 Sync Mode 2 (addition) Sync Mode 3 (readonly)

(replacement)

Figure 30 State diagram for order's synchronization status with sync modes
ISPA client initiates a DMS order in synchronized status “created” by calling <storeNewOrder-
Base>. DMS creates the order and returns its order number. This synchronization mode 1 (“order
extension by replacement”) allows adding jobs with <addJob>, removing existing ones (by calling
<cancelJob>) or updating the order header data with <updateOrderHeader> ISPA client brings
the order to the next state by calling <releaseOrder>. The order is transferred to synchronization
state “confirmedCustomer” - synchronization mode 2 is entered. The order cannot be reduced any
more (“order extension by addition”), only jobs can be added. Cancelling a job is not possible any
more. After DMS invoiced the order, synchronization mode 3 (“readonly access”) becomes the current
mode state. Printing order data is allowed all the time.
Note: ISPA sync mode is only available in ISPA client and will be never transmitted to DMS. It is fully
connected to DMS synchronization status and helps to understand which item actions are allowed in
ISPA’s synchronisation dialog. DMS supporting only LF2 will run automatically in synchronization
mode 3 after sending storeNewOrderBase (no synchronization modes 1 and 2)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 67
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The following two sequence diagrams describe two typical use cases for an example order:

3.6.14.1 Example: Order Creation and Release

The following sequence diagram illustrates creation of an order initiated by a service user in ISPA:
user creates a new appointment using the ISPA check board. The user adds all mandatory appoint-
ment/order data and clicks on “Create new order” button. The order is transferred to DMS and the new
appointment is shown in ISPA’s appointment list. If the user enters the created appointment/order by
choosing “Qualify vehicle”, a synchronization process takes place and results in dialog “Qualify ve-
hicle” showing order detail information. The order is now in synchronization mode 1, the user may
release the order by clicking on “Release order”. DMS performs the state transition and returns the
order’s state back to ISPA. Synchronization mode 2 is active and user’s dialog view is updated.
sd Order Lifecycle - Order Creation and Release

ISPA Client DMS

User creates new appointment using checkboard:

User fills in all appointment data and
clicks on button „Create new order“

storeNewOrderBase
ISPA
sync mode 1 Return syncStatus and lastChangedDMSTimestamp DMS creates new order with
Header data and base data (jobs)

User switches to appointment list

getOrderList(today) with date search param (today)

Return complete order list for today DMS sends all order data
related for today

ISPA Dialog „Appointment List“ is shown:

Synchronization hints
based on lastChangedDMSTimestamp
are visualized in synchronization column

User calls ISPA business case „Qualify Vehicle“

on selected order
getOrderBase(selected order from app. list)

Current order data (header and base) is returned DMS retrieves current DMS order data

ref
ISPA Synchronization Dialog sequence shown in
shown in following diagram

User selects „release order“ command from menu

ISPA DMS performs release order

Order is not in synchronization status „confirmedCustomer“ Synchronization status change
sync mode 2
(„confirmedCustomer“)

Update ISPA dialog view „Qualify vehicle“

Figure 31 Sequence diagram illustrating order creation and release

3.6.14.2 Example: ISPA Synchronization Dialog

As mentioned in last example, synchronization is launched every time user enters for example the
dialog “Qualify vehicle”. This synchronization dialog is shown in the following diagram.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 68
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

sd Order Lifecycle - Synchronization Dialog

ISPA Client DMS

User opens Qualify vehicle view;

sync preparation is launched

ISPA
checkOrderBaseStatus()
sync mode 1
DMS returns status information
Return syncStatus and lastChangedDMSTimestamp „workInProgress“;
a new timestamp is returned

getOrderBase()

Return complete order base and header data Current DMS order data is sent back

Sync dialog is prepared: ISPA and DMS jobs are

compared and analysed to find matching jobs

Sync dialog preparation:

- Synchronize blocked order item positions
- evaluate ISPA order item’s isDirty flag
cancelJob only available in sync mode 2
Sync dialog is opened, user decides which jobs
to modify (add/remove) in DMS and ISPA

seq
cancelJob() – only in sync mode 2

ISPA job has been removed in DMS Removing order item(s) in DMS
sync mode
1 or 2
addJob()

New job is added to DMS, valid jobNumber is returned Adding new order item(s) in DMS

updateOrderHeader()

Order header was updated, new timestamp is stored in ISPA

Sync Dialog closed: ISPA GUI is updated,

ISPA item isDirty flag updated

Figure 32 Example Sequence Diagram of ISPA Synchronization Dialog

It illustrates actions sent to DMS during synchronization process. First after opening the ISPA dialog
“Qualify vehicle” order’s state is checked and the order is sent to ISPA by DMS. Then ISPA synchro-
nizes both order versions (described in change request “order extension” in detail) and enters syn-
chronization dialog for synchronization action on job level. After user interaction order header data is
updated and user returns to dialog “Qualify vehicle”.
Note that cancelJob can only be called in synchronization mode 1.

3.6.14.3 Important order lifecycle issues

• DMS may initiate sync status changes for itself any time. These transitions are represented by
dashed transition lines in Figure 30 above.
• After entering status confirmedCustomer/workInProgress DMS leads in retrieving the current
sync status. If ISPA sync status and DMS sync status of the same order differs, ISPA will copy
DMS sync state and switch its state model of the order.
• Some DMS implement other sync state transitions or skip described states. For example
some DMS doesn’t enter state “confirmedCustomer” and jump to “workInProgress” directly.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 69
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.6.14.4 Continuous order lifecycle

DMS must provide continuous lifecycle access to ISPA. It is very important that no additional and
blocking workflow steps must be performed by user only in DMS for order lifecycle progress.
For example state transition from state “created” to “confirmedCustomer” have to be provided by DMS
by calling releaseOrder without additional manual DMS actions.
Note: Changes to a DMS order are allowed using DMS after creating an order in ISPA. DMS has to
ensure that all actions sent from ISPA to DMS don’t result in “hitting end of the road”: ISPA user has to
be enabled to continue working with an order by using ISPA client and is not compelled to switch to
DMS by default, e.g. after adding jobs to a DMS order.

3.6.15 Creating an order

Sequence diagram
The ISPA user triggers the order creation in the window Entering services and vehicle data (sequence
diagram in Figure 33). Since the DMS is the leading system for customer and vehicle data, ISPA first
checks for regular customers that
• the customer exists in the DMS
• the vehicle exists in the DMS
• all compulsory fields of customer and vehicle data are filled
Therefore ISPA requests the customer details before ISPA transfers the order base. If the customer
does not exist yet in the DMS, ISPA adds the customer. The customer / vehicle methods have been
described in section 3.
• If the customer is marked as passing customer the customer data check is not performed. In-
stead ISPA transfers the customer/vehicle data together with the order base.
• The passing customer concept is not supported by all DMS systems. Therefore it is configura-
ble in the ISPA console whether the field Passing Customer is presented to the ISPA user or
not. It is not presented, the default value "no" is automatically set.
• An order cannot be created if one of the items of the work items list is not known in the DMS.
The method storeNewOrderBaseResponse then return an error instead of an order number.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 70
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 33: Sequence diagram storeNewOrderBase

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 71
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.6.16 Managing the order information within the DMS

3.6.16.1 Order printout

A print instruction can be sent to DMS using method printOrderBase or as part of an order base
(section 4.2.18.5). Depending on the print instruction value a job card (the order printout) and/or a
parts pick list is automatically printed by the DMS. The technician uses the parts pick to get the re-
quired material out of the stock.
If a printout is requested at a second time after first printout and that behavior is not supported by DMS
(printout buttons disabled in DMS), DMS can return an error code like e.g. DMS-xxxx “printing second
pick list is not supported by DMS”. In this case DMS has to describe the new error code, print beha-
viour and relating messages in artifact “content of delivery” (see chapter 7). There is no recommonda-
tion given by this document about DMS printing behavior, please keep the behavior the same as in
DMS environment.

3.6.16.2 Managing the qualified statement and original statement in

the DMS

General
The automatic printout of the workshop order, including the qualified statement customer,
• insures that there is no system break for the service advisor
• provides the necessary information to the workshop
The qualified statement and original statement customer are optional for the following item types of an
order with job status:
• workshop catalog items
• FRUs and SRPs from KSD
• Local FRUs and SRPs
• manual packages
Qualified statements and original statements are transferred from ISPA to the DMS as part of the or-
der base. For details of the structure of a qualified statement see section 3.6.6.
The DMS is responsible for the interpretation and the management of the qualified statement informa-
tion. The rules are:
When an order is displayed in the DMS, the qualified statement has to be displayed, too.
The original statement and qualified statement customer may not be changed by the DMS user.
When one job is put under another job as a substructure, the user has to decide which qualified
statement will be the one for the job.
The qualified statement is part of the workshop order printout (section 0).

The qualified statement and original statement in structured jobs

Each job may have only one qualified statement. When one item with job status is moved under
another job as a substructure, the user has to decide which qualified statement respectively original
statement will be the one for the job. The DMS has to implement this feature. The following cases
have to be considered:
• The job has a qualified/original statement, the subjob has none -> The job retains the qualified
statement
• The job has no qualified/original statement, the subjob has one -> The qualified/original
statement of the subjob becomes the qualified/original statement of the job.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 72
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• Both the job and the subjob have a qualified/original statement -> The user has to decide
which one will become the qualified/original statement of the job.

Formatting and printing the qualified and original statement in the workshop
order printout
The qualified statement is formatted and printed in the workshop order printout. The requirements are:
• The workshop order printout is triggered by ISPA and automatically executed by the DMS.
• The workshop order printout is automatically generated by the DMS without any further user
interaction with a DMS system.
• The qualified and original statement customer is part of the workshop order.
• The qualified and original statement customer is part of the invoice (optional, to be decided by
the market).

Pos Nr Name Quantity

originalStatement 1 4100009 Eliminating body noise 9

Customer statement: strange noises within the

roof area
locationQualified Location: Body, Roof, Slide/tilt sunroof/glass
roof
obervationQualified Type: Noise, Wind Noise
customerStatement qualifiedStatement
Marginal conditions: driving stationary: while
driving, Speed: 100 -150 km/h, Outside
backgroundQualified temperature: 15 -30 °C, Road Condition: Poor
road surface, Frequency: permanent
Please consider the repair history
Note: Don´t adjust driver´s seat
repeatedRepair = „true“
2
Job 2

Figure 34: Mapping of the element names of the XML schema to the printed information
Figure 34 shows the mapping of the element names of the XML scheme to the printed information.
Figure 35 shows an example for the formatting and positioning of the qualified statement in the work-
shop order printout. The actual layout depends on country specific regulations and the dealer compa-
ny corporate design.

Pos Nr Name Quantity

1 4100009 Eliminating body noise 9

Customer statement: strange noises within the

roof area
Location: Body, Roof, Slide/tilt sunroof/glass
roof
Type: Noise, Wind Noise
Marginal conditions: driving stationary: while
driving, Speed: 100 -150 km/h, Outside
temperature: 15 -30 °C, Road Condition: Poor
road surface, Frequency: permanent
Please consider the repair history
Note: Don´t adjust driver´s seat

2
Job 2

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 73
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 35: Formatting and positioning of the Q-wording in the workshop order printout

3.6.17 Display of the order status

Once an order is created in the DMS, the order number, the order state and – if available – the ex-
pected return date is displayed in ISPA. These data are requested by ISPA each time when the list of
the service cases is constructed or updated in ISPA. They are not stored within ISPA.
When in ISPA the tab appointment list in the appointment scheduler is opened, the order data are
requested periodically, by default every 5 minutes.
The state values that ISPA displays are
• created: the order is created in the DMS
• cancelled: the order is cancelled in the DMS
• invoiced: order is completely invoiced. When the order is split, all order parts of all cost units
are invoiced.
ISPA requires that the DMS sends these status.

Sequence diagram check order status

Figure 36: Sequence diagram get order status

3.6.18 Request for order base detail information

After the order creation it is possible that
• work items are added, altered or deleted
• parts are added, altered or deleted
• the job structure is changed.
These modifications can only be made within DMS, not ISPA, after an order is opened. Also there is
no way to update the service case in ISPA automatically when an order is modified in the DMS. The
ISPA user, however, has the possibility to view the details of an order as it is (Figure 37).

Figure 37: Display of order base details in ISPA

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 74
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Sequence diagram

Figure 38: Sequence diagram get order base

For method details for getOrderBase see 4.2.15.
Important: please follow search sequence shown there with given search parameters orderNumber,
orderType and GUID.

3.6.19 Getting a list of DMS orders

The ISPA synchronizer has a method available to request a list of DMS orders. The aim is to store the
orders into the repair history in the BMW central system FBM (vehicle description module).
The DMS delivers a list of the latest orders, starting from a given date. The DMS must always set a
creation date of the order. The creation date may not be a date in the past because is must be as-
sured that all orders are supplied in the response without a gap.
The synchronizer then requests each order of the order list by the method getOrderBase. The data
that are relevant to FBM are extracted and sent to FBM.
• Each market defines during the roll-out planning
• the start date of the orders from when on the orders are added to the repair history in FBM
• whether all data of the DMS are able to be transferred by getOrderBase, especially when
theses data are legacy data.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 75
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 39: Sequence diagram getOrderList

Support for pulsed loading of repair orders:
Due to a possibly large number of repair orders that must be processed by the DMS, especially when
transferring repair order history, there have been problems related to timeouts or crashes on the DMS
side. To prevent these issues, the concept of “pulsed loading” has been introduced into the interface.
The solution is to automatically limit the getOrderListResponse to a certain number of orders. This is
accomplished by dynamically reducing the date range of the getOrderListRequest. If a timeout occurs
the date range is reduced. This process is repeated until the DMS can deliver a response for the set
date range. This pulsed loading is made possible through the availability of the new dateTo field within
the getOrderListRequest (LF4) which in turn has to be evaluated by the DMS. The assumption is that
by reducing the date range for the getOrderListReques, the response time of the DMS will be reduced
as well or the DMS will be able to successfully process the request in the first place. DMS vendors
have to make sure that this assumption holds true. There has to be a date range of more than one day
that the DMS can successfully process in the getOrderlistRequest.
The following outlines the process of transferring repair order history from the DMS to BMW AG by the
ISPA Synchronizer:
1) At the configured start time, the ISPA Synchronizer will send a getOrderListRequest for each
of the existing dealer outlets (as registered on the ISIS) to the DMS, requesting orders for a
potentially long period.The requested date range will initially be the configured dateFrom and
the current date as dateTo. If the DMS cannot successfully process the request the synchro-
nizer will automatically reduce the date range by adapting the dateTo date. The subsequent
getOrderList request will then use the same range but starting with dateFrom date equal to the
previous dateTo date.

2) The ISPA Synchronizer will then call checkOrderBaseStatusRequest for each of the orders
listed in getOrderListResponse.
The DMS responds with checkOrderBaseStatusResponse, transferring all individual order sta-
tus.
3) For each order in status “invoiced”, the ISPA Synchronizer will call getOrderBaseRequest.
The DMS responds with getOrderBaseResponse, transferring the details of each invoiced or-
der.
4) The ISPA Synchronizer removes unneccessary data and sends the repair history order to
BMW AG.
5) At the next ISPA Synchronizer run, the getOrderListRequest will set the creationDateFrom to
the creation date of the last order contained in the previous getOrderListResponse.

Structure of method getOrderList is documented in 4.2.17.

3.6.20 Repair History

Background
The dealer can see all orders from the central repair history in ISPA with following conditions:
• Only orders that have been invoiced are transferred to central repair history. If an order is
cancelled after it was invoiced, it will not be removed from repair history.
• Only orders for brand codes BMW, MINI, RR and MOT will be transferred to central repair his-
tory.
• Only orders that refer to a VIN will be transferred (no lifestyle accessories sales etc.)
If synchronizedStatus of an order is invoiced, a getOrderBase requests is sent to the DMS. The results
of getOrderBaseResponse are then transferred to central repair history and are visible in ISPA Client.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 76
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

If synchronizedStatus of an order is cancelled, the preliminary entry is removed from repair history.
On the ISIS you can configure whether a getOrderBase request is sent or not.
We recommend to send the additional request because usually a DMS returns “cancelled” for every
order it doesn’t know, so a temporary wrong configuration of the DMS interface could mean that open
orders are dropped from the repair history as cancelled.
The getOrderList interface method is used exclusively for repair history transfer. It allows ISPA to iden-
tify orders that were not created via ISPA but directly inside the DMS and then transfer them to repair
history.

No Authentication Requirement (new in LF4)

The requests that are used to transfer the repair history should be accessible without user authentica-
tion so that the transfer to the repair history does not depend on the configuration of correct username
and password (and does not silently stop because someone changed his password). Any user authen-
tication has to be accepted.
This applies to:
- getSetupValues
- getOrderList
- checkOrderBaseStatus
- getOrderBase
- resetOrderChangeFlag
(Note: The status updatedInvoice and the method resetOrderChangeFlag are reserved
for future use. DMS implementing according to this interface contract are not required
to implement this status and method.)

3.6.21 Updating DMS Order Header (LF3, LF4)

Before releasing an order the client can update order header information by using the method upda-
teOrderHeader (4.2.19).

3.6.22 Job Handling

With LF4 an advanced job handling was integrated into DMS – ISPA interface: Jobs can now be add-
ed to an existing order or offer, and jobs from an existing offer or order can be canceled. In addition,
the the header of an existing offer or order can be updated (for example, with current data from the
vehicle ignition key). At the end an offer can be turned into an order by releasing (finalizing) it. All de-
scribed job features here are only available if the supportedFeatureLevel is LF4. Regarding backward
compatibility the former order life cycle is still supported for DMS with supportedFeatureLevel LF3 (just
adding of new jobs to an order) or LF2 (no adding or deleting of jobs) inside getSetupValuesRes-
ponse.

3.6.22.1 Adding a job to a DMS order

To add a job to an existing DMS order, ISPA client calls the method addJob. The following figure
shows the request signature with all required elements: schemaRef, userInformation, order, job, time-
stamp, orderType. Jobs are identiefied by its jobIdentifier created by DMS system. ISPA Client can
recommend a jobIdentifier and pass it in the <job>.<jobIdentifier> element. E.g. if 2 jobs exists in an
order with IDs 1 and 2 ISPA Client passes ID 3. DMS may return another ID if recommended ID is not
valid in DMS by returning a valid ID. ISPA will store that ID as valid item ID. After that no job ID
change is allowed any more.
Technical description of addJob can be found in 4.2.21.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 77
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3.6.22.2 Cancel a job of an DMS order

After adding at least one job to a DMS order it can be cancelled (removed). Mandatory elements are
the userInformation, the order (where the job is added), the jobIdentifier and the timestamp.
ISPA may cancel more than one using one request by passing a list of job identifiers.
All elements and attributes are visualized in 4.2.23.

3.6.22.3 New job related error codes

See chapter 5.3 for error codes used by job related method calls or responses.

3.6.23 Release a DMS Order

3.6.23.1 Releasing <= LF2

See <storeNewOrderBase>.

3.6.23.2 Release Order Variant in LF4

With introduction of job handling (adding, cancelling) there is a new way to release a DMS order. ISPA
client can call method <releaseOrder> to finalize a DMS order in LF4. Note that printing is done by
new LF4 method <printOrderBase> (printing was also offered in <storeNewOrderBase>). A
<timestamp>, the orderNumber to release, userInformation and languageCode are mandatory fields
(see 4.2.19.2).
If finalization was successful, the response holds no errors and the mandatory element <orderRe-
leaseConfirmed> is TRUE.

3.6.24 Sync status change from updatedInvoice (LF4)

If DMS performs a status change from “updatedInvoice” back to “invoiced” ISPA must be informed by
DMS calling request <resetOrderChangeFlag>.
Note: The status updatedInvoice and the method resetOrderChangeFlag are reserved for future
use. DMS implementing according to this interface contract are not required to implement this
status and method.

3.7 Qualified workshop statement

The technician in the workshop has the possibility to add a qualified statement to any job of an order.
To do this the DMS should supply a function to launch a web browser to open the workshop statement
management web page. This web page takes care of handling workshop statements. The DMS only
needs to supply the function to open this web.
The requirements are:
• The DMS user interface displays a button next to each job that launches the workshop state-
ment management web page. If the job has already an existing workshop statement the icon
should be different to when the job has no workshop statement (see workshopState-
ment_v01.01.00.xsd for details on how to retrieve existing workshop statement via a web ser-
vice)
• If the user clicks on a button the DMS should open a web browse and access the workshop
statement management web page on URL:http://<<ISIS_IP>>:8095/wsstmt_web/ workshops-
tatement.do?method=show&guid=YY&job=XX&language=ZZ.
• A workshop statement can only be deleted within the workshop statement management web
page.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 78
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The qualified workshop statement will be written into the ISPA database.

Figure 40 shows a sketch of a DMS mask as a suggestion with a job list and for each job
• a checkbox whether a qualified statement customer exists
• a checkbox whether a qualified statement workshop and
• a button to create respectively edit a qualified workshop statement

Job Job description Qualified Qualified Add /

Statement statement modify
no. customer workshop Q st. WS

1 Inspection

2 Technical Campaign
➾
3 Change wheels

4 Replace rear window

➾ ➾

Figure 40: DMS job list with button to input the qualified workshop statement (suggestion)
The XML scheme workshopStatement_v01.01.00.xsd [12] defines an ISPA service. It provides
the information about the qualified statements workshop which is stored in the ISPA database.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 79
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4 Technical Interface
This chapter describes schemas and lists webservice methods (request and response) and related
types in detail.

4.1 XML Schemas

The methods, the element types, the elements and the attributes are defined in three XML schemes
• scoreDMSgeneric_v04.00.06.xsd: all methods except order relevant methods
• orderDMS_v04.00.06.xsd: order relevant methods
• scoreGenericTypes_v04.00.06.xsd: basic types
• workshopStatement_v01.02.00.xsd: workshop statement related topics
This document lists the relevant subtrees of the schemes in a graphical manner, the Content Model
View of the tool Altova XML Spy. The valid reference, however, always is the latest released version of
these schemes.
The versioning of the schemes corresponds to the versioning of the interface contract (section 1.4).
Two technical methods, which are described in section 6.5 and 6.6, are defined by the schemes
• versionLookup_v01.00.02.xsd
• logger_V01.07.00.xsd

4.2 XML Methods

Every method call has a webservice request part and a webservice response part. This chapter visua-
lizes all method calls and gives selected examples of requests and responses.

4.2.1 Method scoreDMSgeneric::getSetupValues (LF 4)

The mandatory element <supportedFeatureLevel> is introduced. The content is the information of the
DMS to the ISPA Broker which delivery stage DMS supports. Presently the allowed values are LF1,
LF2, LF3 and LF4. The broker eventually transforms the messages if the delivery stages of the
DMS and the ISPA client are different. This transformation does not affect the DMS side of the inter-
face. The mandatory element <supportedFeatureLevel> may return the value LF4. There’s also a
printer list available to specify favorite printers in <printOrderBase> calls.
• The new settings are requested each time the ISPA System Console is being closed (resp.
lock is released)

Figure 41: Method getSetupValues

<getSetupValues xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 80
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<userInformation>
<userID>Q123456</userID>
<firm>NORMANDY AVENUE</firm>
<branch>A</branch>
<language>de-DE</language>
<workplaceID>WMUC123456</workplaceID>
<password>Password</password>
</userInformation>
</getSetupValues>

Sample 1 Listing of getSetupValues

4.2.1.1 Response scoreDMSgener-

ic::getSetupValuesResponse (LF 4)
The DMS returns to ISPA lists of mandatory fields, value ranges and additional fields of an error object
if the method fails (Figure 42).
• The response has to be an error or a result, passing an error and results at the same time is
not allowed
• supportedFeatureLevel has to be LF2 (LF1 not supported anymore)
• ISPA will not add new customers until all mandatory fields have been filled. They appear in
blue in ISPA.
• Values for mandatory fields must reference fields that are part of typeCustomerDetail
• Flex Fields are additional customer / vehicle field fields ISPA will display.
• Flex Fields for orders and jobs are not used by the current ISPA Client version.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 81
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 42: Structure of method getSetupValuesResponse (LF 4)

4.2.1.2 Configurable Settings

 Wildcard Characters
Only * or % are allowed for search requests.
 Mandatory Fields
for vehicle/customer creation (ISPA Client will highlight them in blue and make sure they are
present before adding a customer/vehicle record)
 Value Ranges for the following fields are mandatory:
title, salutation, gender, VAT Groups, brand, language
 Value Ranges for the following fields are optional:
profession, hobby, branch, preferredContactMethod, country, county, state, customerIndicator,
customerGroup
 Flex Fields: Additional data fields that the DMS requires but that do not exist in ISPA. ISPA
will display them as additional customer/vehicle fields

4.2.1.3 Values in Value Range List in detail

According to type typeValueRangeList please ensure thate codes and display values are pro-
vided from DMS:

Typically * or %.

Every value range has always

code and displayValue:
ISPA will display the
“displayValue” to the user, but
send the “code” to the DMS.

Here you can define value ranges for all customer and
vehicle data fields that ISPA knows.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 82
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.1.4 Mandatory fields

The mandatory field list consists of zero or more mandatory fields. The value of the attribute name is
an XML schema name of a customer field (Table 3), a vehicle field (Table 4) or the name of a flexible
field.
Many DMS fill certain field values by themselves. For example they set the model code and the series
automatically when the VIN is given. These fields must be optional in ISPA.
In the ISPA window Customer data (Figure 6), mandatory fields are visually highlighted dynamically.
Before adding or changing customer/vehicle data in DMS, ISPA has to check that there are values
given for all mandatory fields.

4.2.1.5 Value range lists

The structure of the value range lists is shown in .
If the DMS allows a wildcard to be used within a search field, for example "*'", the DMS tells ISPA the
wildcard in the setup values. See section 3.4.5.
There are predefined elements for value ranges for
• Title (mandatory)
• Salutation (optional)
• Gender (mandatory)
• VAT Group (mandatory)
• Brand (optional)
• Language (mandatory)
The element <valueRangeOptional> has an attribute name. The value of the attribute name is a
XML schema name of a customer field (Table 3), a vehicle field (Table 4) or the name of a flexible
field.
Optional value ranges are given for example for the fields
• Profession
• Hobby
• Profession Branch
• Preferred contact method
• Country
• County
• State
• Customer Indicator
• Customer Group
During the planning of a roll-out in a market, the roll-out team defines for each DMS which attributes
will have value ranges.
The values of each value range are given in a suitable display order. One value may be signed as
default. This value is expected for a new customer, if the user does not select a different value. Values
that are used by existing data but are not valid for adding or changing may be signed as deprecated.
If a field has a value range list assigned and the field is not a mandatory field, the default value shall
be set to "no value", " " or similar.

A single value of a value list is represented by a <line> element which consists of a <code> and a
<displayValue> element, both of type string. If the value list belongs to a flexible field (see be-
low) the content of the <code> element must match the data type pattern of the corresponding flexible
field (attribute dataType of <flexFieldCustomer> resp. <flexFieldName>). The DMS is re-
sponsible to ensure this match.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 83
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Example: If a flexible field customer exists with displayName="Does customer like his
Car?" and dataType boolean, the allowed contents of <code> are only:
<code>true</code>
<code>false</code>

4.2.1.6 Returning valid brand codes

Concerning the mandatory value range list valueRangeBrand the following statements are to be
considered:
1. The DMS supplies the attributes code and displayValue for each vehicle of the BMW
group brands BMW, Mini and Rolls Royce. Here the following codes are to be supplied by the
DMS:
 "MINI" for Mini
 "BMW" for BMW
 "RR" for Rolls Royce
 "MOT" for BMW Motorcycle
2. These code values are used by several operations in ISPA, e. g. for the setup of a new vehicle
and the storing a new order base (see point 4 below).
3. Additionally the DMS may also supply the non BMW group brands within this value range list.
4. ISPA sends the brand codes, which are supplied by the DMS (BMW, MINI, RR, MOT and
supplied non BMW group brands) back to the DMS within the method storeNewOrderBase
(section 3.6.7).
The element type <brandType> contains all BMW group brands. The element type <brandTypeO-
pen> contains general car brands and includes the BMW group brands.

Annotation
If the DMS is using different codes internally (e.g. 1=BMW, 2=MINI, 3=AUDI, 4=Mercedes …),it still
has to understand the four brand codes given above. If necessary, a mapping has to be configured in
the DMS, so that in this example, the results would look like this:
code: BMW description: BMW Cars
code: MINI description: MINI Cars
code: 3 description: AUDI Cars
code: 4 description: Mercedes Cars
BMW and MINI then would have to be mapped to 1 and 2 inside the DMS.

4.2.1.7 Additional fields (flexible fields)

The structure of flexible fields is shown in Figure 43. There are separate fields for customer data
(<flexFieldCustomer>) and vehicle data (<flexFieldVehicle>). A flexible field may be manda-
tory and may have a value list assigned. It is up to the systems DMS and ISPA to ensure the consis-
tency by the name attributes.
In ISPA flexible fields are only displayed in the window Customer data. ISPA supplies a feature within
the system console to configure the order of the fields in the window Customer data.
Flexible fields for order data and job data are not yet used. They may be used in the future.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 84
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

currently not used,

reserved for future use

Figure 43: Structure of the flexible field list

The attribute dataType of the type typeFlexField is a string. The content may be of one of the
following types:
• string (max. 120 chars)
• number (max. 10 digits)
• decimal (max. 10 digits, 2 decimal digits)
• date (YYYY-MM-DD)
• boolean (true | false)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 85
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.1.8 List of available DMS printers (Version 3.1.4 - LF4)

In delivery state 4 printing is possible before and after calling method <releaseOrder>. Regarding
to DMS printing capabilities several printers are available, <printerList> returns a list of printers
available for printing. In method <printOrderBase> there is a new optional element printer which
can be submitted with one entry from the printer list.
Be aware that this list is optional, if no printer is returned it does not mean no printer might be availa-
ble: it means you cannot choose any printer.

4.2.1.9 Sample listing

<getSetupValuesResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<valueRangeList>
<wildcard>*</wildcard>
<valueRangeTitle>
<line isDeprecated="false" isDefault="false">
<code>ARCH</code><displayValue>Architekt</displayValue>
</line>
...
<line isDeprecated="false" isDefault="false">
<code>SPRLU</code><displayValue>SPRLU</displayValue>
</line>
</valueRangeTitle>
<valueRangeSalutation>
<line isDeprecated="false" isDefault="false">
<code>F</code><displayValue>Frau</displayValue>
</line>
...
<line isDeprecated="false" isDefault="false">
<code>HUF</code><displayValue>Herr und Frau</displayValue>
</line>
</valueRangeSalutation>
<valueRangeGender>
<line isDeprecated="false" isDefault="false">
<code>M</code><displayValue>Male</displayValue>
</line>
<line isDeprecated="false" isDefault="false">
<code>F</code><displayValue>Female</displayValue>
</line>
</valueRangeGender>
<valueRangeVatGroup>
<line isDeprecated="false" isDefault="false">
<code>GWL_DRITT</code><displayValue>Garantieabwicklung
</displayValue>
</line>
...
<line isDeprecated="false" isDefault="false">
<code>SERVICEMOB</code><displayValue>Servicemobil</displayValue>
</line>
</valueRangeVatGroup>
<valueRangeBrand>
<line isDeprecated="false" isDefault="false">
<code>ALFA</code><displayValue>Alfa Romeo</displayValue>
</line>
...
<line isDeprecated="false" isDefault="false">

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 86
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<code>BMW</code>
<displayValue>BMW</displayValue>
</line>
<line isDeprecated="false" isDefault="false">
<code>MINI</code><displayValue>Mini</displayValue>
</line>
<line isDeprecated="false" isDefault="false">
<code>MOT</code><displayValue>Motorrad</displayValue>
</line>
<line isDeprecated="false" isDefault="false">
<code>RR</code><displayValue>Rollce Royce</displayValue>
</line>
...
</valueRangeBrand>
<valueRangeLanguage>
...
<line isDeprecated="false" isDefault="false">
<code>DE</code><displayValue>Deutsch</displayValue>
</line>
--
</valueRangeLanguage>
<valueRangeOptional name="profession">
...
<line isDeprecated="false" isDefault="false">
<code>ANGESTELL</code><displayValue>Angestellter</displayValue>
</line>
<line isDeprecated="false" isDefault="false">
<code>ARBEITER</code><displayValue>Arbeiter</displayValue>
</line>
...
</valueRangeOptional>
...
<valueRangeOptional name="country">
<line isDeprecated="false" isDefault="false">
<code>AD</code><displayValue>ANDORRA</displayValue>
</line>
...
<line isDeprecated="false" isDefault="false">
<code>ZW</code><displayValue>ZIMBABWE</displayValue>
</line>
</valueRangeOptional>
...
</valueRangeList>
<mandatoryFieldList>
<mandatoryField name="address1"/>
<mandatoryField name="brand"/>
<mandatoryField name="city"/>
<mandatoryField name="firstName"/>
<mandatoryField name="lastName"/>
<mandatoryField name="modelCode"/>
<mandatoryField name="numberPlate"/>
<mandatoryField name="postCode"/>
<mandatoryField name="vatGroupCode"/>
<mandatoryField name="vin"/>
</mandatoryFieldList>
<flexFieldsList></flexFieldsList>
<supportedFeatureLevel>LF4</supportedFeatureLevel>
<printerList>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 87
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<printer>
<uniquePrinterName>HP LaserJet 772</uniquePrinterName>
<printerDescription>Kopierraum 1-23 1.OG (HP LaserJet)</printerDescription>
</printer>
<printer>
<uniquePrinterName> Brother TRW-21</uniquePrinterName>
<printerDescription>Flur 2-0 2.OG (Brother TRW)</printerDescription>
</printer>
</printerList>
<DMSInformation>
<DMSName>ultimateDMS</DMSName>
<DMSVersion>4.32</DMSVersion>
<supportedPackagetype>SRP</supportedPackagetype>
<supportsFastlaneFlag>false</supportsFastlaneFlag>
<supportsValueLineFlag>true</supportsValueLineFlag>
</DMSInformation>
</getSetupValuesResponse>

Sample 2 Listing of getSetupValuesResponse

4.2.2 Method scoreDMSgeneric::searchCustomer

A single customer result has the structure depicted in Figure 98 and Figure 99. The structure is quite
similar to the structure of the customer details (section 3.4.2).
Figure 44 shows the structure of the search request for customer/vehicle data.
The search window in ISPA offers the search criteria as follows. In the window Select customer / ve-
hicle (DMS) there are:
• Registration No.
• Name
• First name
• Social security number
• Customer number
• Matchcode
• Telephone
• VIN
In the mask Update customer / vehicle in the appointment planner the search criteria are:
• Registration No.
• Name
• Customer number
• Matchcode
• Telephone
• VIN
• Make
• Model
• Series
• Postal code
• Notes
• Technical campaign with number, description, status, associated with appointment
The DMS shall be able to receive a search request with all possible customer/vehicle attributes of the
method searchCustomer of Figure 44. The mapping of the ISPA names listed above to the XML
interface names is listed in Table 3 and Table 4.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 88
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 44: Structure of a customer/vehicle search request

4.2.2.1 Response scoreDMSgener-

ic::searchCustomerResponse
The customer result list returns all entries found from a case insensitive search. There might be more
than one car that belongs to a customer, but ISPA uses a simpler data model. ISPA searches for a
customer using the vehicle identification number (VIN) or the customer number.
For searchCustomer this means:
• If a customer has more than one car: Return more than one result (same customer informa-
tion, different car data)
• If a car is attached to different customers: Return the main contact only (usually the owner)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 89
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 45: Structure of searchCustomerResponse

4.2.2.2 Case-insensitive search

Presently the search in the ISPA database is case sensitive but it will be altered to a case insensitive
search in the future. Therefore the search in the DMS shall be case insensitive from the beginning.
A search result list can consist of a large number of customer data sets. Therefore ISPA sends a value
for the maximum number of data sets which shall be returned by the DMS in one search response.
The value is sent in the element <maxResultPartition>. It is configured by ISPA, a good value is
100. A second request and following request send the starting position for the next customer data set
to be returned in the element <resumeSearchToken>.
<searchCustomer xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation>
<userID>Q123456</userID>
<firm>NORMANDY AVENUE</firm>
<branch>A</branch>
<language>de-DE</language>
<workplaceID>WMUC123456</workplaceID>
<password>Password</password>
</userInformation>
<vin>WBAAP71020PP38538</vin>
<maxResultPartition>100</maxResultPartition>
</searchCustomer>

Sample 3 Listing of searchCustomer, search by VIN

If the DMS allows a wildcard to be used within a search field, for example "*'", the DMS tells ISPA the
wildcard in the setup values. See section 4.2.1.5.

<searchCustomer xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation>
<userID>Q123456</userID>
<firm>NORMANDY AVENUE</firm>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 90
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<branch>A</branch>
<language>de-DE</language>
<workplaceID>WMUC123456</workplaceID>
<password>Password</password>
</userInformation>
<numberPlate>M-VE*</numberPlate>
<maxResultPartition>100</maxResultPartition>
</searchCustomer>

Sample 4 Listing of searchCustomer, search by registration number with wildcard

4.2.2.3 Blocked customers and customers marked for deletion

Blocked customers and customers marked for deletion are not returned in the results list of sear-
chCustomerResult. Note: This is different behavior to getCustomerDetailsResponse (section
3.4.6).

4.2.2.4 Resume search option

If there are more search results than specified in the <searchCustomer> request, <searchCustomer-
Response> has to allow the user to access the search results page by page.
In order to achieve this, a resumeToken has to be sent. The resumeToken is a String that is sent by
ISPA in order to tell the DMS that it wants to resume the specified search, so for example the next 100
results should be supplied:
searchCustomer () searchCustomer searchCustomer searchCustomer
(resumeToken1) (resumeToken2) (resumeToken3)

The search found

Results Results Results 315 results.
Results
100 – 200 – 300 –
0-99
199 299 314
The last searchCustomerResponse
resumeToken1 resumeToken2 resumeToken3 should not include a resumeToken!

4.2.3 Method scoreDMSgeneric::getCustomerDetails

Up to version 3.1, the customer number had been mandatory and the VIN optional. Within the context
of the introduction of the Passing Customer concept, a getCustomerDetails would not work, since
a Passing Customer does not possess a customer number. So the method getCustomerDetails
has been changed. To ensure the consistency (seen from the DMS), however, also the call of get-
CustomerDetails must be possible. Especially in the case if the Passing Customer gets the state of
a regular customer in the DMS afterwords.
• If the content of a field was deleted in the DMS and shall therefore be deleted in ISPA as well,
send the empty XML tag. <city /> deletes the value for City.
• If a field is not supported by the DMS, omit the tag completely.
The Core Component ISPA has to follow the rules:
a) If customer number and VIN are known
both data must be supplied.
b) If either customer number or VIN is not known
the known information must be supplied.

Element <customerNumber> optional instead of mandatory

Return also VIN in response (getCustomerDetailsResponse)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 91
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

For retrieveing customer details ISPA can query detailed information using…
• …just the VIN
If the car exists, return all customers that are attached to this car + the vehicle details.
• …just the customer number
If the customer exists, return the customer and all his cars.
• …both
Return the details only if the VIN and customer both exist and are linked.

Figure 46: Structure of the method getCustomerDetails

<getCustomerDetails xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation> ... </userInformation>
<customerIdentification>
<customerNumber>0110550</customerNumber>
<vin>WBAAP71020PP38538</vin>
</customerIdentification>
</getCustomerDetails>

Sample 1 Listing of getCustomerDetails

4.2.3.1 Response scoreDMSgener-

ic::getCustomerDetailsResponse
• If only VIN or customer is given there may be more than one record found.
• Customers might have more than one car, and cars might be connected to more than one
customer.
• If VIN+customer number are specified, only one result should be returned.
• In case of an error, one <customer> set is mandatory, but it may contain just <error> and
<customerIdentification>.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 92
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 47: Structure of the method getCustomerDetailsResponse

<getCustomerDetailsResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<customerIdentification>
<customerNumber>120014</customerNumber>
</customerIdentification>
<customerDetails>
<vehicleReference>
<vin>WBAAP71020PP38538</vin>
<numberPlate>M-VE 3300</numberPlate>
<mileage units="km">48000</mileage>
<registrationDate>2005-03-01</registrationDate>
<brand>BMW</brand>
<modelDesignation>320d Touring</modelDesignation>
<modelCode>AP71</modelCode>
<devSeriesCode>E46</devSeriesCode>
<engineType>D</engineType>
<gearCodeLetter>SCH</gearCodeLetter>
<manufacturingDate>2005-02-01</manufacturingDate>
<selfSale>false</selfSale>
<legalInspectionDate>2008-03-01</legalInspectionDate>
<emissionControlInspectionDate>2007-03-01
</emissionControlInspectionDate>
</vehicleReference>
<lastName>Softlab GmbH</lastName>
<matchCode>SOFTLAB GMBH</matchCode>
<telPrivate>089/9936-0</telPrivate>
<telCommercial>089/9936-1579</telCommercial>
<lastContactDate>2007-02-23</lastContactDate>
<emailCommercial>[email protected]</emailCommercial>
<faxCommercial>040-43188554</faxCommercial>
<mobileCommercial>0163 4212 596</mobileCommercial>
<preferredContactMethod>E-Mail</preferredContactMethod>
<isAftersalesMarketingBlocked>true</isAftersalesMarketingBlocked>
<companyName>BMW International</companyName>
<branch>A</branch>
<address1>Zamdorfer Straße 120</address1>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 93
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<postCode>81677</postCode>
<city>München</city>
<country>DE</country>
<firstName>Human Resources</firstName>
<languageCode>DE</languageCode>
<genderCode>M</genderCode>
<furtherNotes/>
<customerIndicator>KD_INL</customerIndicator>
<creditIndicator>false</creditIndicator>
<creditLimit>0.00</creditLimit>
<lastChange>2007-02-23</lastChange>
<isCompany>false</isCompany>
<vatRegNumber/>
<vatGroupCode>KD_INL</vatGroupCode>
<bankingAccount>1234324557</bankingAccount>
<taxPayersAccountNumber>34234</taxPayersAccountNumber>
<allocatedDate>1967-08-13</allocatedDate>
</customerDetails>
</getCustomerDetailsResponse>

Sample 1 Listing of getCustomerDetailsResponse (1 customer)

The DMS returns a list of customer numbers and the affiliated customer details of an error if the cus-
tomer does not exist in the DMS (Figure 47). For each customer number given by getCustomerDetails
the customer data set is returned.
Since in one getCustomerDetails request now several customers may be found, the customer data
(<customerNumber>, <customerDetails> is wrapped in an additional element <customer>. So it will be
no more necessary to process the request sequentially. Either the customer number or the VIN or
both must be supplied.
See section 3.4.2 for the customer data structure. The customer details element references zero or
more vehicles. The structure of the vehicle information is described in section 3.4.3.

4.2.4 Method scoreDMSgeneric::addCustomer

In order to add a new customer and his vehicle in the DMS, ISPA calls the method addCustomer and
transmits the following data to the DMS (Figure 48).

Figure 48: Structure of method addCustomer

Before sending the method, ISPA checks whether all mandatory attributes have values assigned.
ISPA sends a customer details element (see section 3.4.2) with a reference to one vehicle (see sec-
tion 3.4.3). Optional elements are only sent when they have a content or are explicitly empty. Note that
the delivery stage 2 the customer details may have additional fields (flexfields, see section 4.2.1.7).
The DMS ignores all elements which do not correspond to a field of the DMS. These are not stored in
the DMS and not returned to ISPA.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 94
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The DMS checks whether the attribute customer number is set. If yes, the customer already exist in
the DMS and is changed (updated). If not the customer doesn't exist yet and is added in the DMS.

Important: ISPA will send an addCustomer only if

• either all mandatory fields are filled in
(these were retrieved by getSetupValuesReponse)
• or if an order shall be opened – because opening the order requires a customer number.

If a user creates an appointment in ISPA for a new customer and not all mandatory fields are filled in,
the client will not send an addCustomer request.

If ISPA sends addCustomer, because all mandatory fields have been filled, and the DMS responds
with an error message, it will be suppressed (idea: Always be able to make an appointment). Error
messages are only shown when the customer cannot be created before transferring the order to the
DMS (it needs a customer number).

4.2.4.1 Sample Listing

<addCustomer xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation>
<userID>Q123456</userID>
<firm>NORMANDY AVENUE</firm>
<branch>A</branch>
<language>de-DE</language>
<workplaceID>WMUC123456</workplaceID>
<password>Password</password>
</userInformation>
<customerDetails>
<vehicleReference>
<vin>WBADM41000GM11972</vin>
<numberPlate>0</numberPlate>
<mileage units="km">32500</mileage>
<registrationDate>1999-10-15</registrationDate>
<brand>BMW</brand>
<modelDesignation>523IA</modelDesignation>
<modelCode>DM41</modelCode>
<colour code=""/>
<upholstery code=""/>
<legalInspectionDate>2003-01-01</legalInspectionDate>
<emissionControlInspectionDate>2003-01-01
</emissionControlInspectionDate>
<nextMaintenanceDistance units="km">0</nextMaintenanceDistance>
<nextChangeOfGearBeltDistance units="km">0
</nextChangeOfGearBeltDistance>
</vehicleReference>
<lastName>A.L. PAAMEI MERKAVA</lastName>
<telPrivate>0972/50214939</telPrivate>
<telCommercial>0972/35338344</telCommercial>
<isAftersalesMarketingBlocked>true</isAftersalesMarketingBlocked>
<address1>SHAKED22NEVE MONSON POB</address1>
<postCode>60190</postCode>
<city>ISRAEL</city>
<firstName>Firma</firstName>
<creditIndicator>false</creditIndicator>
<creditLimit>0.000000</creditLimit>
<isCompany>false</isCompany>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 95
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<vatGroupCode>KD_AUSL</vatGroupCode>
</customerDetails>
</addCustomer>

Sample 1 Listing of method addCustomer

4.2.4.2 Response scoreDMSgeneric::addCustomerResponse

The DMS returns the customer number or an error element if it could not create the customer/vehicle
data set (Figure 49). The customer number is the key attribute of the record. ISPA writes the customer
number in its cached customer/vehicle data set. This indicates that the customer/vehicle has been
stored in the DMS.
• If the DMS has access to a chassis range file,
the values for <brand>, <modelDesignation>, <modelCode> and <devSeriesCode> should be
checked against it.
• If the values do not match, the DMS should automatically correct them in order to prevent in-
sertion of garbage (e.g. user enteres devSeriesCode “F1” instead of “F01”).
(This only applies to brands BMW, MINI, RR and MOT.)

Figure 49: Structure of the method addCustomerResponse

Sample Listing
<addCustomerResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<customerNumber>120120</customerNumber>
</addCustomerResponse>

Sample 2 Listing of method addCustomerResponse

4.2.5 Method scoreDMSgeneric::changeCustomer

In order to update existing customer/vehicle data in the DMS, ISPA transmits the following data to the
DMS. The element <customerDetails> is of type typeCustomerDetails.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 96
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 50: Structure of the method changeCustomer

Sample instance
<changeCustomer xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation>
<userID>Q123456</userID>
<firm>NORMANDY AVENUE</firm>
<branch>A</branch>
<language>de-DE</language>
<workplaceID>WMUC123456</workplaceID>
<password>Password</password>
</userInformation>
<customerNumber>120014</customerNumber>
<customerDetails>
<vehicleReference>
<vin>WBAAP71020PP38538</vin>
<numberPlate>M-VE 3300</numberPlate>
<mileage units="km">48000</mileage>
<registrationDate>2005-03-01</registrationDate>
<brand>BMW</brand>
<modelDesignation>320d Touring</modelDesignation>
<modelCode>AP71</modelCode>
<devSeriesCode>E46</devSeriesCode>
<engineType>D</engineType>
<gearCodeLetter>SCH</gearCodeLetter>
<manufacturingDate>2005-02-01</manufacturingDate>
<colour code=""/>
<upholstery code=""/>
<selfSale>false</selfSale>
<legalInspectionDate>2008-03-01
</legalInspectionDate>
<emissionControlInspectionDate>2007-03-01
</emissionControlInspectionDate>
<nextMaintenanceDistance units="km">0
</nextMaintenanceDistance>
<nextChangeOfGearBeltDistance units="km">0
</nextChangeOfGearBeltDistance>
</vehicleReference>
<lastName>Softlab GmbH</lastName>
<matchCode>SOFTLAB GMBH</matchCode>
<telPrivate>089/9936-0</telPrivate>
<telCommercial>089/9936-1579</telCommercial>
<lastContactDate>2007-02-23</lastContactDate>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 97
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<emailCommercial>[email protected]</emailCommercial>
<faxCommercial>040-43188554</faxCommercial>
<mobileCommercial>0163 4212 596</mobileCommercial>
<preferredContactMethod>E-Mail</preferredContactMethod>
<isAftersalesMarketingBlocked>true
</isAftersalesMarketingBlocked>
<companyName>BMW International</companyName>
<branch>A</branch>
<address1>Zamdorfer Stra&#223;e 120</address1>
<postCode>81677</postCode>
<city>M&#252;nchen</city>
<country>DE</country>
<firstName>Human Resources</firstName>
<languageCode>DE</languageCode>
<genderCode>M</genderCode>
<customerIndicator>KD_INL</customerIndicator>
<creditIndicator>false</creditIndicator>
<creditLimit>0.000000</creditLimit>
<lastChange>2007-02-23</lastChange>
<isCompany>false</isCompany>
<vatGroupCode>KD_INL</vatGroupCode>
<customerGroup>PASS</customerGroup>
</customerDetails>
</changeCustomer>

Sample 1 Listing of changeCustomer

The method is only called if DMS relevant fields have changed. Optional elements are only sent by
ISPA if they have changed (the content has changed or the element has become explicitly empty.
Note that the delivery stage 2 the customer details may have additional fields (flexfields, see section
4.2.1.7).
The DMS ignores all elements which do not correspond to a field of the DMS. The customer number
exists because the customer has been added to the DMS before. The customer is identified by the
customer number, which is its key attribute. If the customer does not exist any more, e. g. he has been
physically deleted, the DMS returns an error in the response.

4.2.5.1 Response scoreDMSgener-

ic::changeCustomerResponse
If during the customer change an error occurred, the DMS delivers an error element to ISPA. An “emp-
ty” response means success.

Figure 51: Structure of the method changeCustomerResponse

Sample Listing
<changeCustomerResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 98
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

</changeCustomerResponse>

Sample 2 Listing of changeCustomerResponse

4.2.6 Method scoreDMSgeneric::getLocalFlatRateGroupList

Figure 52: content of method getLocalFlatRateGroupList

<getLocalFlatRateGroupList xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation> ... </userInformation>
<vin>WBAAP71020PP38538</vin>
</getLocalFlatRateGroupList>

Sample 1 Listing of getLocalFlatRateGroupList

4.2.6.1 Method scoreDMSgener-

ic::getLocalFlatRateGroupListResponse
The DMS returns a vehicle specific list of local flat rate groups ISPA. Each list entry consists of an
identifier and a description. If the DMS does not support FRU groups, it will return all FRUs within one
group.

Figure 53: content of method getLocalFlatRateGroupListResponse

The FRU groups are displayed at the left half of the DMS catalogue window.

<getLocalFlatRateGroupListResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 99
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<flatRateGroupListEntry>
<localFlatRateGroupID>0000</localFlatRateGroupID>
<description>Wartung / Inspektion</description>
</flatRateGroupListEntry>
<flatRateGroupListEntry>
<localFlatRateGroupID>0011</localFlatRateGroupID>
<description>Wartung / Öwechsel/Reinigung</description>
</flatRateGroupListEntry>
...
<flatRateGroupListEntry>
<localFlatRateGroupID>9962</localFlatRateGroupID>
<description>Lackierung / Heckklappe</description>
</flatRateGroupListEntry>
</getLocalFlatRateGroupListResponse>

Sample 2 Listing of getLocalFlatRateGroupListResponse

If the list of local Flat Rate Groups contains empty entries, the empty groups should be omitted.

4.2.7 Method scoreDMSgeneric::getLocalFlatRateGroup

Figure 54: Content of method getLocalFlatRateGroup

The group is identified by its ID. The DMS returns the list of flat rates that belong to a local flat rate
group with a given identifier. The list is specific for a VIN. The list entries contain the complete informa-
tion about the FRUs.

<getLocalFlatRateGroup xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation> ... </userInformation>
<vin>WBAAP71020PP38538</vin>
<localFlatRateGroupID>0000</localFlatRateGroupID>
</getLocalFlatRateGroup>

Sample 1 Listing of getLocalFlatRateGroup

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 100
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.7.1 Method scoreDMSgener-

ic::getLocalFlatRateGroupResponse

Figure 55: Content of method getLocalFlateRateGroupResponse

The type typeFlatRateEntry has the additional element <hasFixedPrice>, which is introduced
to provide for marketing SRPs / FRUs (section 3.5.5.2).
<getLocalFlatRateGroupResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<localFlatRateGroupID>0000</localFlatRateGroupID>
<flatRateListEntry>
<flatRateNumber>0012160</flatRateNumber>
<description>HU nach § 29 DEKRA</description>
<quantity>1.00</quantity>
<isLocal>true</isLocal>
<hasFixedPrice>false</ hasFixedPrice >
</flatRateListEntry>
<flatRateListEntry>
<flatRateNumber>FLISPA1</flatRateNumber>
<description>ISPA TEst0</description>
<quantity>0.00</quantity>
<isLocal>true</isLocal>
<hasFixedPrice>false</hasFixedPrice>
</flatRateListEntry>
</getLocalFlatRateGroupResponse>

Listing of getLocalFlatRateGroupResponse

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 101
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.8 Method scoreDMSgeneric::getLocalFlatRateDetails

Figure 56: Structure of method getLocalFlatRateDetails

<getLocalFlatRateDetails xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation>...</userInformation>
<vin>WBAAP71020PP38538</vin>
<flatRateNumber>0012160</flatRateNumber>
</getLocalFlatRateDetails>

Sample 1 Listing of getLocalFlatRateDetails

4.2.8.1 Response scoreDMSgener-

ic::getLocalFlatRateDetailsResponse

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 102
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 57: Structure of method getLocalFlatRateDetailsResponse

The type typeFlatRateEntry has the additional element <hasFixedPrice>, which is introduced to
provide for marketing SRPs / FRUs (section 3.5.5.2).
<getLocalFlatRateDetailsResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<flatRateEntry>
<flatRateNumber>0012160</flatRateNumber>
<flatRateUnitType>FRU</flatRateUnitType>
<description>HU nach § 29 DEKRA</description>
<quantity>1.00</quantity>
<isLocal>true</isLocal>
<hasFixedPrice>false</hasFixedPrice>
</flatRateEntry>
</getLocalFlatRateDetailsResponse>

Listing of getLocalFlatRateDetailsResponse

4.2.9 Method scoreDMSgeneric::getLocalSRPGroupList

Figure 58: Content of method getLocalSRPGroupList

ISPA expects that the local SRPs are organized in SRP groups and that the groups which are applica-
ble to a vehicle are identifiable by the VIN. ISPA requests the SRP groups through the method get-
LocalSRPGroupList, technical details are explained in 4.2.9.
The DMS performs a database query and returns a vehicle specific list of the local SRP groups. Each
group entry consists of an identifier and a description. The list may be empty. The SRP groups are
displayed on the left half of the DMS catalogue window. If an error occurs it is returned by an error
element. If the DMS does not support FRU groups, it will return all FRUs within one group.

<getLocalSRPGroupList xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation> ... </userInformation>
<vin>WBAAP71020PP38538</vin>
</getLocalSRPGroupList>

Sample 1 Listing of getLocalSRPGroupList

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 103
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.9.1 Response scoreDMSgener-

ic::getLocalSRPGroupListResponse

Figure 59: Content of method getLocalSRPGrouListResponse

<getLocalSRPGroupListResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<localSRPGroupListEntry>
<localSRPGroupID>2610</localSRPGroupID>
<description>Gelenkwelle / Visko-Zentralsperre</description>
</localSRPGroupListEntry>
...
<localSRPGroupListEntry>
<localSRPGroupID>2624</localSRPGroupID>
<description>Gelenkwelle / Viskosekupplung</description>
</localSRPGroupListEntry>
</getLocalSRPGroupListResponse>

Sample 1 Listing of getLocalSRPGroupListResponse

If the list of local SRP Groups contains empty entries, the empty groups should be omitted.

4.2.10 Method scoreDMSgeneric::getLocalSRPGroup

Figure 60: Content of method getLocalSRPGroup

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 104
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The user selects one of the SRP groups in the window "DMS catalogue". ISPA triggers the DMS to
give back a list of SRPs of this group. The list is specific for the given VIN. The group is identified by
its ID.

The DMS returns a list of SRPs which belongs to a selected local SRP group to ISPA. Each list entry
consists of the SRP number, a description and optional additional notes. The list may be empty. If an
error occurs it is returned in an error element.

4.2.10.1 Response scoreDMSgener-

ic::getLocalSRPGroupResponse

Figure 61: Content of getLocalSRPGroupResponse

4.2.11 Method scoreDMSgeneric::getLocalSRPDetails

Figure 62: Content of getLocalSRPDetails

When the user selects a local SRP in order to add it to the items catalogue of the service case, ISPA
requests the details of the local SRP. SRP is identified by its number. All parameters and response
details are shown in 4.2.11.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 105
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.11.1 Response scoreDMSgener-

ic::getLocalSRPDetailsResponse

Figure 63: Content of method getLocalSRPDetailsResponse

As the response to the query after the details of a local SRP, the DMS delivers the details to ISPA
(Figure 63). The SRP number is the same as the requested one. In the scheme parts as well as FRUs
are optional. However, in reality an SRP consists of at least one FRU and usually at least one part. A
part is represented by the element partListEntry, a FRU is represented by the element flatRa-
teUnitListEntry.
Change in version 3.1.1: The package type is an enumeration of the values (SRP | MRP | GRP).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 106
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.12 Method scoreDMSgeneric::getLocalPartDetails

Figure 64: Content of method getLocalPartDetails

In order to get the details of an entered part number, ISPA queries the DMS with the following data.
VIN is not transferred to the DMS. Here, the ISPA user is responsible that the requested part fits to the
vehicle of the service case. "Local" in the name of the method refers to that the request is sent to the
DMS rather than that only local part can be requested.
If the part is known in the DMS, ISPA inserts it into the work items list of the service case. If not, an
error element is returned.

<getLocalPartDetails xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation>
<userID>Q123456</userID>
<firm>NORMANDY AVENUE</firm>
<branch>A</branch>
<language>de-DE</language>
<workplaceID>WMUC123456</workplaceID>
<password>Password</password>
</userInformation>
<partNumber>34351164371</partNumber>
</getLocalPartDetails>

Sample 1 Listing of getLocalPartDetails

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 107
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.12.1 Response scoreDMSgener-

ic::getLocalPartDetailsResponse

Figure 65: Content of method getLocalPartDetailResponse

Local parts own an optional element <isFluid> to indicate if a part is fluid. If the flag is missing, the
part is treated as non-fluid. If DMS does not know the state of the part, it should skip this element. See
also <typeGenericPart>.<isFluid>.

<getLocalPartDetailsResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<partEntry>
<partNumber>34351164371</partNumber>
<isLocal>true</isLocal>
<description>Oil OI2832</description>
<brand>BMW</brand>
<isFluid>true<isFluid>
</partEntry>
</getLocalPartDetailsResponse>

Sample 1 Listing of getLocalPartDetailsResponse

4.2.13 Method scoreDMSgeneric::getPriceInformation

In order to get the price information of all items of the items list (work items and parts), ISPA sends the
request getPriceInformation to the DMS. Technical features of this method are shown in 4.2.13.
The customer number refers to the keeper of the vehicle, as defined in the customer/vehicle data
record. The DMS uses the customer number to calculate customer specific prices. If neither the cus-
tomer number nor the VIN is given the DMS will return the list prices (catalog prices).
If the order has been already created, the optional element <orderIdentification> is present. It
contains the GUID of the order and the order number as set by the DMS.
The VIN is mandatory. Without the VIN no specific prices can be calculated. When not customer num-
ber is given and the VIN element is empty the DMS will return the list prices (catalog prices).
The request for price information contains

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 108
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• a list of flat rate units (optional) of type typeFlatRatePriceRequest (Figure 102)

• a list of parts (optional) of type typePartPriceRequest (Figure 103)
• a list of packages (optional) (Figure 67)
The quantity of FRUs is the number of time units needed. The order split percentage denominates
which percentage has to be paid by the customer (section 3.5.7).

Figure 66: Content of method getPriceInformation

• Always return prices from a customer’s point of view.

Service contracts, dealer internal billing and warranty do have different price calculation.
• Use it to give an early warning: If a position won’t go through with storeNewOrderBase, al-
ready throw an error with getPriceInformationResponse.
• If a fixed price is transferred, calculate the tax and compute the missing gross or net price.
• Return default prices if customer/VIN are unknown –
ISPA can ask for prices without VIN and customer number. In this case a customer calling on
the phone asks for a rough estimate. – Use a “default VIN” and “default customer” in such a
case.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 109
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• Fail per position, not globally: Return an error element instead of the request availabili-
ty/price, but transfer all the other results.
• Check against existing order: If an order number is specified, the prices have to be checked
against that order so that any fixed prices that were assigned inside the DMS order are taken
into account (and not just list / customer prices).
If a DMS supports quotes/pre-orders and orders (uses <orderType>) it should search first the
quotes/pre-orders and then the orders.

4.2.13.1 Request for prices for all items together instead of one re-
quest for each item
Presently ISPA requests the price information for only one FRU, SRP or part at each call. The meth-
ods getPriceInformation and getPriceInformationResponse allow transmitting an arbitrary
number of items. This will be used in LF2 to enhance performance. ISPA will request the prices for the
complete work items list within one call. The DMS must be able to handle this list for returning the
price information.
• FRU price requests are encapsulated by type typeFlatRatePriceRequest, see 4.3.12.
• A list of parts is optional (Figure 103). Each part is identified by the part number. Quantity is
the number of pieces of that part. The order split percentage denominates which percentage
has to be paid by the customer. See section 3.5.7.
• The SRP list (package list) is optional (Figure 67).
• The DMS returns price information on flat rates, parts and packages at ISPA (4.3.13).
• Corresponding to the lists of FRUs, parts and SRPs (packages), the DMS returns lists of pric-
es for these items. It is the job for ISPA to fill in the price information into the respective rows
of the item list.

4.2.13.2 Prices for flat rate units

If a flat rate unit is not known in the DMS, the price is "0" and an error is returned that the flat rate unit
is not known. An order cannot be created if a part is not known.

4.2.13.3 Prices for parts

TypePartPriceEntry is shown in 4.3.14.
If a part is not known in the DMS dealer database, the customer specific price cannot be calculated. In
this case the DMS searches the part in the central BMW database. If the part is found here, the DMS
returns the price of the central BMW database as retail price and as customer specific price.
If the part is found neither in the DMS dealer database nor in the central BMW database, the price is
returned as "0" and an error is returned that the part is not known. An order cannot be created if a part
is not known.
If a BMW part has been replaced by a dealer individual part, the elements of the element group
groupPartReplacement exist and have the content of the replaced part number, the replaced part
description and optionally a replacement description.

4.2.13.4 Prices for packages

If a package is not known in the DMS, the price is "0" and an error is returned that the package is not
known. An order cannot be created if a package is not known.
As a sample for the package price, see Sample 1 where a part is contained in an SRP.
The element grossPrice contains the customer specific gross price.
The SRP list (package list) is optional.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 110
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 67: Element <package> in request <getPriceInformation>

Two sample listings are given in Sample 1 and Sample 2.
<getPriceInformation xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation> ... </userInformation>
<customerNumber>120014</customerNumber>
<vin>WBAAP71020PP38538</vin>
<flatRate>
<number>0000221</number>
<flatRateUnitType>FRU</flatRateUnitType>
<isLocal>false</isLocal>
<quantity>15.000000</quantity>
<orderSplitPercentage>40.000000</orderSplitPercentage>
</flatRate>
</getPriceInformation>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 111
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Sample 1 Listing of method getPriceInformation for a simple FRU (order split percentage
40 %)
<getPriceInformation xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation> ... </userInformation>
<customerNumber>120120</customerNumber>
<vin>WBADM41000GM11972</vin>
<package isLumpSum=”false” isLocal=”false”>
<packageNumber>51346711DM410</packageNumber>
<packageType>SRP</packageType>
<flatRate>
<flatRateUnitNumber>5134671</flatRateUnitNumber>
<flatRateUnitType>FRU</flatRateUnitType>
<quantity>8.000000</quantity>
<orderSplitPercentage>100.000000</orderSplitPercentage>
</flatRate>
<part>
<quantity>1.000000</quantity>
<number>51348159171</number>
<isLocal>false</isLocal>
<isFluid>false</isFluid>
<brand>BMW</brand>
<orderSplitPercentage>100.000000</orderSplitPercentage>
</part>
</package>
</getPriceInformation>

Sample 2 Listing of method getPriceInformation for a SRP

4.2.13.5 Response scoreDMSgener-

ic::getPriceInformationResponse

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 112
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 68: Content of method getPriceInformationResponse

Here's a listing for the price information for a FRU.

<getPriceInformationResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<flatRateUnitPrice>
<flatRateUnitNumber>0000221</flatRateUnitNumber>
<description>BMW-Inspektion I inkl.</description>
<additionalInfo>Additional infos...</additionalInfo>
<numberOfUnits>15</numberOfUnits>
<retailPrice>37.50</retailPrice>
<customerSpecificDiscount>0.00</customerSpecificDiscount>
<customerSpecificPrice>15.00</customerSpecificPrice>
<hasFixedPrice>no</hasFixedPrice>
<taxRate>16.00</taxRate>
<grossPrice>17.40</grossPrice>
</flatRateUnitPrice>
</getPriceInformationResponse>

Sample 1 Listing of method getPriceInformationResponse for a FRU (order split

percentage 40 %)

PackagePrice in Response

Figure 69: element packagePrice

Here's a listing of a package price information.
<getPriceInformationResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<packagePrice>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 113
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<packageNumber>51346711DM410</packageNumber>
<isLumpSum>SRP</packageType>
<retailPrice>113.18</retailPrice>
<customerSpecificDiscount>0.00</customerSpecificDiscount>
<customerSpecificPrice>113.18</customerSpecificPrice>
<taxRate>16.00</taxRate>
<grossPrice>131.29</grossPrice>
<hasFixedPrice>no</hasFixedPrice>
<isLumpSum>false</isLumpSum>
<flatRateUnitPrice>
<number>5134671</number>
<isLocal>false</isLocal>
<quantity>8</quantity>
<description>Türfensterscheibe hinten</description>
<additionalInfo>Additional infos...</additionalInfo>
<retailPrice>52.00</retailPrice>
<customerSpecificDiscount>0.00</customerSpecificDiscount>
<customerSpecificPrice>52.00</customerSpecificPrice>
<taxRate>16.00</taxRate>
<grossPrice>60.32</grossPrice>
<hasFixedPrice>no</hasFixedPrice>
</flatRateUnitPrice>
<partPrice>
<description>Window</description>
<quantity>1.00</quantity>
<number>51348159171</number>
<isLocal>false</isLocal>
<isFluid>false</isFluid>
<retailPrice>61.18</retailPrice>
<retailGrossPrice>73.20</retailGrossPrice>
<customerSpecificDiscount>0.00</customerSpecificDiscount>
<customerSpecificPrice>61.18</customerSpecificPrice>
<hasFixedPrice>no</hasFixedPrice>
<taxRate>16.00</taxRate>
<grossPrice>70.97</grossPrice>
<specialTaxRate>0</specialTaxRate>
<discoutKey>1</discoutKey>
<priceChangeDate>2003-01-16</priceChangeDate>
<replacedPartNumber/>
<replacedPartDescription/>
<replacementDescription/>
<numberOnStock>0.00</numberOnStock>
<numberOnStockMin>2.00</numberOnStockMin>
<storagePlace>LAGER1</storagePlace>
</partPrice>
</packagePrice>
</getPriceInformationResponse>

Sample 1 Listing of method getPriceInformationResponse for an SRP

4.2.14 Method scoreDMSgeneric::checkPartsAvailability

In order to check the parts stock ISPA sends a request with the following structure.
The DMS supplies the parts stock information to ISPA. Parts may be on stock
• in the home branch. This is the outlet the ISPA user is linked to in the user information.
• in other branches, if the dealer possesses more than one branch.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 114
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The availability information for the home branch is stored in the elements <numberOnStock> and
<availabilityFlag>. ISPA displays the stock in the column Availability in the User Interface
(Figure 26). The availability information for the other branches is stored in the element part <availa-
bilityBranch> (section 3.5.8.3).
In version 3.01.01, a mandatory element <isLocal> of type Boolean is added. If the part is a DIP,
the value of the element is "true", else "false".
• Fail per position, not globally: Return an error element instead of the request availabili-
ty/price, but transfer all the other results.

Figure 70: Content of method checkPartsAvailability

4.2.14.1 Element Details

brand of the car (not the part brand, e.g. “Bosch”!): ISPA uses the brand codes of the DMS; they are
transmitted by getSetupValuesResponse.
The brand codes for BMW, MINI, Rolls Royce and BMW Motorrad are hard-coded: BMW, MINI, RR,
MOT
productType indicates whether a car or motorcycle is used:
• optional – you cannot rely on it
• possible values: “car”, “motorcycle”

4.2.14.2 Sample listing

<checkPartsAvailability xmlns="http://www.bmw.com/score">
<schemaRef refSchema="scoreDMSgeneric" version="04.00.06"/>
<userInformation> ... </userInformation>
<vin>WBADM41000GM11972</vin>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 115
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<brand>BMW</brand>
<partList>
<part>
<partNumber>51348159171</partNumber>
<brand>BMW</brand>
</part>
</partList>
</checkPartsAvailability>

Sample 2 Listing of method checkPartsAvailability

4.2.14.3 Response scoreDMSgener-

ic::checkPartsAvailabilityResponse

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 116
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 71: Content of the method checkPartsAvailibilityResponse

4.2.14.4 Availability and Replaced Parts

If a part is replaced by another part, optinal element typePartAvailabitli-
ty.groupPartReplacement.replacedPartNumber contains the current part number. The same
is valid for optional elements replacedPartDescription and replacementDescription.

4.2.14.5 Parts superseding/exchanging

Dealers can choose to exchange a BMW part for a local part, e.g. use their own oil instead of BMW oil.
This replacement is referred to “DIP” (dealer individual parts).
BMW regularly issues new spare parts that replace older spare parts for the same function. This func-
tionality is referred to as parts superseding.
checkPartsAvailabilityResponse tells ISPA that a certain part was exchanged with a local one. ISPA
will then include the local part instead of the BMW part in the appointment and then in the order that is
sent to the DMS.
If checkPartsAvailabilityResponse doesn’t return every replacement/superseding correctly, the DMS in
likely to reject storeNewOrderBase because it contains invalid parts!
It lists a parts availability response for a dealer without a branch structure.
<checkPartsAvailabilityResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<partsAvailability>
<partNumber>51348159171</partNumber>
<numberOnStock>0.00</numberOnStock>
<availabilityFlag>false</availabilityFlag>
<isLocal>false</isLocal>
</partsAvailability>
</checkPartsAvailabilityResponse>

Sample 3 Listing of method checkPartsAvailibilityResponse (dealer with no branches)

4.2.15 Method orderDMS::getOrderBase

ISPA calls the method getOrderBase (Figure 72) to request the details of an order base.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 117
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 72: Structure of method getOrderBase

The GUID is now optional.

4.2.15.1 Search Sequence for orders using getOrderBase

ISPA is able to pass several search parameters for finding the requested order:
• orderNumber (mandatory)
• GUID (optional)
• orderType (LF4,optional, valid values are “preorder” or “order”)
This optional element should only used by DMS if it differs between preorders and orders. Or-
derType is meant as a hint, not exclusion.

ISPA saves orderNumber, GUID and orderType (if available) for a single order. Everytime an order is
requested using getOrderBase ISPA passes available search parameters to DMS.
GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011
 BMW Group Page 118
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Search Rules
• If orderType is empty, all preorders and orders are queried, GUID is used for distinction
• If orderType is “preorder”, first DMS preorder pool is queried, than DMS order pool.
• If orderType is “order”, DMS order pool is queried, preorder pool is skipped in search.
• GUID: If the query has multiple results, GUID is used to identifiy one result.

Search Example A
<orderNumber>WSAUF307620</orderNumber>
<GUID>14GM11972000890120070227154606</GUID>
<orderType>order</orderType>
DMS looks only in order pool and scans there for orderNumber WSAUF307620. GUID may be used
for better search performance.

Search Example B
<orderNumber>WSAUF307623</orderNumber>
<orderType>preorder</orderType>
DMS looks first in preorder pool and scans there for orderNumber WSAUF307623. If no result is
found, all orders are examined. GUID may be used for better search performance.

Search Example C
<orderNumber>WSAUF307625</orderNumber>
<GUID>33GM11972000890120070227154607</GUID>
DMS looks in preorder and order pool (orderNumber WSAUF307625). If more than one result is found,
the given GUID decides which result is the final one.

4.2.15.2 Sample Listing

Here is a listing of a call of getOrderBase (Sample 1).
<getOrderBase xmlns="http://www.bmw.com/score">
<schemaRef refSchema="orderDMS" version="04.00.06"/>
<userInformation>
<userID>Q123456</userID>
<firm>NORMANDY AVENUE</firm>
<branch>A</branch>
<language>de-DE</language>
<workplaceID>WMUC123456</workplaceID>
<password>Password</password>
</userInformation>
<dealer distributionPartnerNumber="00089" outletNumber="01"
warrantyDealerNumber="01299"/>
<orderNumber>WSAUF307620</orderNumber>
<GUID>14GM11972000890120070227154606</GUID>
<orderType>order</orderType>
</getOrderBase>

Sample 1 Listing of method getOrderBase

4.2.15.3 Response orderDMS::getOrderBaseResponse

The DMS returns the details of a requested order through the method getOrderBaseResponse.
The order base structure is explained in detail in section 3.6.3.
The response has been extended to return a lastChangedDMSTimestamp in LF4.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 119
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 73: Structure of the method getOrderBaseResponse

4.2.16 Method orderDMS::checkOrderBaseStatus

ISPA requests the order status as shown in Figure 74 in technical description of chapter 4.2.16.
The checkOrderBaseStatus request can ask for the status of one order or of the staus of a whole list
of orders. Be sure to include this in your tests, i.e. do not run test cases that always ask for one order
status only.
Status Fields: In checkOrderBaseStatusResponse and getOrderBaseResponse there are two status
values, and they have a different meaning:
• dmsStatus is a free text field. Transfer the order status the same way it would be displayed in
the DMS, i.e. in local language. This value will be displayed to the user.
• synchronizedStatus is an enumeration, i.e. only the values “created”, “cancelled” and “in-
voiced” are allowed. This value is intended for ISPA to automatically react correctly to a status
change.
Change from version 3.0 to version 3.1.0: The GUID is now optional.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 120
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 74: Content of method checkOrderBaseStatus

<checkOrderBaseStatus xmlns="http://www.bmw.com/score">
<schemaRef refSchema="orderDMS" version="04.00.06"/>
<userInformation> ... </userInformation>
<dealer warrantyDealerNumber="01299"
distributionPartnerNumber="00089"
outletNumber="01" />
<orderIdentification>
<GUID>14GM11972000890120070227154606</GUID>
<orderNumber>WSAUF307620</orderNumber>
</orderIdentification>
</checkOrderBaseStatus>

Sample 1 Listing of method checkOrderBaseStatus

4.2.16.1 Response orderDMS::checkOrderBaseStatusResponse

The response of the DMS contains the following data which are delivered to CC ISPA.
A new optional element <returnDateExpected> of type date (day and time) contains the expected
return date of the vehicle. The date can differ from the planned returned date (<returnDatep-
lanned>), for example when the delivery of parts delays or labors are added in the workshop. <re-
turnDateExpected> should be set by the DMS, if possible.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 121
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 75: Content of method checkOrderBaseStatusResponse

<checkOrderBaseStatusResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<orderBaseStatus>
<orderIdentification>
<GUID>14GM11972000890120070227154606</GUID>
<orderNumber>WSAUF307620</orderNumber>
</orderIdentification>
<synchronizedStatus>created</synchronizedStatus>
<dmsStatus>angelegt</dmsStatus>
</orderBaseStatus>
</checkOrderBaseStatusResponse>

Sample 1 Listing of method checkOrderBaseStatusResponse

4.2.17 Method orderDMS::getOrderList

• If creationDateTo is missing: Return all orders that were created between today and creation-
DateFrom. Otherwise return the orders that were created between creationDateFrom and cre-
ationDateTo (including both dates).
• If creationDateFrom is in the future, return an empty list of orders.
• This function is not called by the ISPA Client, but by the ISPA program logic on the ISIS.
There is a separate configuration dialogue that triggers this at:
http://<ispa-vm-ip-address>:8095/synchronizer/jsp/synchronizer.jsp

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 122
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 76: Structure of method getOrderList

<getOrderList xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<userInformation>...</userInformation>
<dealer warrantyDealerNumber="01299"
distributionPartnerNumber="00089"
outletNumber="01" />
<creationDateFrom>2010-08-13</creationDateFrom>
<creationDateTo>2010-10-13</creationDateTo>
</getOrderList>

4.2.17.1 Response orderDMS::getOrderListResponse

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 123
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

In LF4, a new element totalResults has been introduced: Return the amount of orders that match
the search criteria in there. Should access to one of the orders that match the search criteria not be
possible, skip it. For LF4 lastChangedDMSTimestamp must be returned to ISPA.

<getOrderListResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/
<totalResults>2</totalResults>
<orderListEntry>
<orderNumber>23423423</orderNumber>
<GUID>GUID-34-324-763</GUID>
<synchronizedStatus>created</synchronizedStatus>
<dmsStatus>angelegt</dmsStatus>
<vehicleIdentification>7463823</vehicleIdentification>
<brand>BMW</brand>
<lastChangedDMSTimestamp>2010-10-17T09:30:47Z</lastChangedDMSTimestamp>
</orderListEntry>
<orderListEntry>
<orderNumber>4829234</orderNumber>
<GUID>GUID-44-324-7234</GUID>
<synchronizedStatus>created</synchronizedStatus>
<dmsStatus>angelegt</dmsStatus>
<vehicleIdentification>7463854</vehicleIdentification>
<brand>MINI</brand>
<lastChangedDMSTimestamp>2010-09-15T10:03:30Z</lastChangedDMSTimestamp>
</orderListEntry>
</getOrderListResponse>

4.2.18 Method orderDMS::storeNewOrderBase

4.2.18.1 Order Header interpretation and storage

Because every request contains potentially new and updated order header data, DMS must interprete
and persist all order header data sent by ISPA. For example mileage information, dealer details and
order status information must be transmitted to DMS and stored there.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 124
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Order header data is available in storeNewOrderBase.orderBase.groupOrderHeader.

See groupOrderHeader in 4.5.11 for detailed information. This step is identical to updateOrder-
Header-requests.

4.2.18.2 Order Base Handling and transactional context

Every request owns a complete order base structure with jobs, packages, parts and FRUs. DMS
should store these structures including all attributes and elements (see also fallback options for limited
DMS in 3.6.4.3). After changing DMS data order pool, order’s timestamp (lastChangedDMSTimeS-
tamp) must be updated by DMS and sent back to ISPA in response part. This timestamp must be
changed as last action, at the end of transactional context.

4.2.18.3 Order Identification

The DMS returns (Figure 78, Sample 1 in section 4.2.18)
• the GUID
• the order number if the order has been successfully created or
• an error element if not.
The GUID (global unique identifier) is generated by a software component, triggered by ISPA. The
GUID identifies a service case and an order. It has been transferred to the DMS by storeNewOrder-
Base and is returned here. It may not be changed by the DMS. If storeNewOrderBase has not
transmitted aGUID, updateOrderHeader may pass a GUID. DMS must persists this transmitted GUID
and never change it by itself.
The order number is generated by the DMS. It identifies the order and may not be changed after crea-
tion.

4.2.18.4 Error handling

The error element gives the possibility to
• return overall errors, e. g. "invalid customer number" and
• individual errors for a particular part, FRU, package or job.
An order cannot be created if one of the items of the work items list is not known in the DMS. The
method storeNewOrderBaseResponse then return an error instead of an order number.
Note that in delivery state 4 (LF4) no choice construction is used, orderNumber and orderBaseErrors
turned to be optional elements.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 125
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 77: Structure of method storeNewOrderBase

4.2.18.5 Order Split Handling

There are two ways to deal with order split information in storeNewOrderBase:
• Act upon the customer number that is specified

• Act upon the cost unit

4.2.18.6 Referencing Service Advisors

Every order is attached to a service advisor. The service advisor is the one the customer has an ap-
pointment with.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 126
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

This can be someone different from the user who is logged on, e.g. the service assistant Julia is
logged on; she is taking a call from a customer and organizes an appointment for the customer with
service advisor Romeo.

In this example, “Julia” would be sent as userID in the authentication block, but “Romeo” would be
sent as serviceAdvisorID in storeNewOrderBase.

4.2.18.7 Technical Campaigns

Technical Campaigns are transferred as local FRUs, consting of 11 digits (product type + 10 charac-
ters special defect code).
<flatRateUnit isLocal="true" number="10011580200">
<description>ISPA TC-1-0011580200</description>
<quantity>15.000000</quantity>
<hasPartsClearing>false</hasPartsClearing>
<orderSplit>
<percentage>100.00</percentage>
<costUnit>Warranty</costUnit>
</orderSplit>
<retailPrice>0.000000</retailPrice>
<customerSpecificPrice>0.000000</customerSpecificPrice>
<hasFixedPrice>false</hasFixedPrice>
<taxRate>0.000000</taxRate>
<grossPrice>0.000000</grossPrice>
</flatRateUnit>

If the Technical Campaign is not known to the DMS, it should be saved as a text position – reminding
the mechanic to perform the Technical Campaign. Technical Campaigns should be returned in getOr-
derBaseResponse the same way they were received – disguised as local SRPs.

4.2.18.8 Order printout information

The optional element <additionalText> in <groupInvariantOrderHeader> is added in the
order base information (section 3.6.3.1). Its content is a general note on the order that is created by
the service advisor. If needed, the can be printed out on the order printout.
The workshop order shall print the name of the service advisor in charge of the return of the vehicle
(identified by the content of element <returnServiceAdvisorID> and the planned date of the
vehicle return (content of the element <returnDatePlanned>)).
The optional element <printInstruction> of the method storeNewOrderBase has two optional
flags (type boolean) (Figure 77):
• <printJobCard> : if "yes" print out the workshop order document
• <partsPickList>: if "yes" print the list for the technician with the parts needed for the order
• <printInstruction> is placed in method storeNewOrderBase (see chapter 4.2.18).
Printouts can be also started using method printOrderBase.
• <printer>: extended print selection in <printInstructions> available (optional)
The customer statement has to be printed on the job card for documentation.
Create a String from
the Qualified Statement XML structure (VFC).

4.2.18.9 Parts reservation due date in field creationDate (LF4)

In order for parts reservation (LF4, also see) to work, the DMS must be provided with information
about the repair date of the repair order on which the parts are needed. This is necessary e.g. to de-
termine whether missing parts have to be ordered via express ordering or using the default parts rep-
lenisment process. Until now (<LF4) the <creationDate> of a repair order was the date the order
was transferred from ISPA to the DMS, as it was only transferred once upon arrival of the customer.
Since with parts reservation / order extension the order will be transferred multiple times, the creation

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 127
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

date would only denote the date of the intial order transmission from ISPA to DMS. But this date can
not be used for parts reservation. Due to a lack of a scheduled repair date for the order the creation-
Date field will be reused to contain exactly this information: The date the repair order is scheduled for.
That means with LF4 the DMS can use the information in the creationDate field to determine until
when reserved parts are needed.

4.2.18.10 Response orderDMS::storeNewOrderBaseResponse

Figure 78: Structure of the method storeNewOrderBaseResponse

For LF4 lastChangedDMSTimestamp must be returned to ISPA.

Listing
<storeNewOrderBaseResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<GUID>14GM11972000890120070227154606</GUID>
<orderNumber>WSAUF307620</orderNumber>
<lastChangedDMSTimestamp>2010-10-30T09:00:00</lastChangedDMSTimestamp>
</storeNewOrderBaseResponse>

Sample 1 Listing of method storeNewOrderBaseResponse

4.2.18.11 Price Handling

The price handling has been updated in LF4: The element <hasFixedPrice> is no longer sent from
ISPA to the DMS. It still exists in getOrderBaseResponse and getPriceInformationResponse as to
inform ISPA that a price cannot be changed by the service advisor. ISPA however only sends a price
or discount in getPricenInformation, addJob or storeNewOrderBase if is considered a fixed price or
discount that has to be taken into account by the DMS.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 128
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.19 Method orderDMS::updateOrderHeader (LF4)

Figure 79 Structure of method updateOrderHeader

If storeNewOrderBase has not transferred a GUID, ISPA may pass a GUID to DMS by using element
<GUID>. DMS has to store it and return it for future responses (e.g. getOrderList).
Header information was separated into two groups and has been merged into groupOrderHeader. For
layout reasons header can be seen in Figure 134.

4.2.19.1 Transactional Context and DMS timestamp update

After updating DMS order header with the given data, DMS must generate, store and return a new
lastChangedDMStimestamp at the end of this transaction.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 129
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 80 Structure of the updateOrderHeaderResponse

For LF4 lastChangedDMSTimestamp must be returned to ISPA.

4.2.19.2 Usage of creationDate as scheduled repair date

As described in 4.2.18.9 the field creationDate will contain the date the repair order is scheduled for.
The DMS must interpret this date to determine until when reserved parts are needed.

4.2.20 Method orderDMS::releaseOrder (LF4)

Figure 81 Structure of method releaseOrder (LF4)

4.2.20.1 Transactional Context and DMS timestamp update

After releasing a DMS order, DMS must generate, store and return a new lastChangedDMStimes-
tamp at the end of this transaction.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 130
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.20.2 Response orderDMS::releaseOrderResponse

Figure 82 Structure of method response releaseOrderResponse (LF4)

For LF4 please return lastChangedDMSTimestamp to ISPA.

4.2.21 Method orderDMS::resetOrderChangeFlag (LF 4)

This method is designed to reset the synchronizedStatus of an order from updatedInvoice to invoiced.
Note: The status updatedInvoice and the method resetOrderChangeFlag are reserved for future
use. DMS implementing according to this interface contract are not required to implement this
status and method.

Figure 83 Structure of resetOrderChangeFlag (LF 4)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 131
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.21.1 Response orderDMS::resetOrderChangeFlagResponse

Figure 84 Structure of resetOrderChangeFlagResponse

4.2.22 Method orderDMS::addJob (LF3, LF4)

Figure 85 Structure of method addJob

DMS sends a response with addJobResponse and informs the caller if the job identifier was accepted
by DMS. If not, the chosen ID is passed as a mandatory element to the client (see Figure 86). Errors
are listed in element <errors>. There is an optional search parameter element <vin>, that may be
used to optimize search in DMS.
<addJob xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<userInformation>...</userInformation>
<order>
<GUID>GUI-324-54323</GUID>
<orderNumber>887262763</orderNumber>
<orderType>order</orderType>
<vin vinLongPrefix="38294738172347234" vinShort="3829473" inputIndicator="M"/>
</order>
<job>
<jobIdentifier>102</jobIdentifier>
<jobDescription>Job A</jobDescription>
<jobComment>test</jobComment>
<customerStatement>
<originalStatement>Tür knarzt</originalStatement>
<qualifiedStatement>
<observation>
<description>Rechte Fahrertür Geräusch</description>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 132
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

</observation>
<location>
<description>Rechte Fahrertür </description>
</location>
<backgroundList>
<background>
<description>Tür</description>
</background>
</backgroundList>
<position>
<description>Fahrertür</description>
</position>
</qualifiedStatement>
<repeatedRepair>false</repeatedRepair>
</customerStatement>
<partList>
<part>...
</part>
</partList>
<flatRateUnitList>
...
</flatRateUnitList>
<packageList>
...
</packageList>
<orderSplit>
<percentage>1.12</percentage>
<costUnit>Service Inclusive</costUnit>
<customerNumber>3453245234</customerNumber>
<accountNumber>83737</accountNumber>
<accountName>SERVICE_324234</accountName>
</orderSplit>
</job>
</addJob>

4.2.22.1 Transactional Context and DMS timestamp update

After updating DMS order with the given job, DMS must generate, store and return a new lastChan-
gedDMStimestamp at the end of the transaction.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 133
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.2.22.2 Response orderDMS::addJobResponse

Figure 86 Structure of method response addJobResponse

<addJobResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<jobIdentifier>2147483647</jobIdentifier>
<lastChangedDMSTimestamp>2010-11-01T10:35:49Z</lastChangedDMSTimestamp>
</addJobResponse>

4.2.23 Method orderDMS::cancelJob (LF4)

Figure 87 Structure of method cancelJob

Cancel job cancels one or more jobs in DMS. There is an optional search parameter element <vin>,
that may be used to optimize search in DMS.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 134
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<cancelJob xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<userInformation>…</userInformation>
<order>
<GUID>GUID-34-23454</GUID>
<orderNumber>8392873</orderNumber>
<orderType>order</orderType>
<vin vinLongPrefix="8372837664329837" vinShort="8372837" inputIndicator="M"/>
</order>
<jobIdentifier>103</jobIdentifier>
<jobIdentifier>104</jobIdentifier>
<jobIdentifier>106</jobIdentifier>
</cancelJob>

4.2.23.1 Transactional Context and DMS timestamp update

After removing one or more jobs from DMS order, DMS must generate, store and return a new last-
ChangedDMStimestamp at the end of this transaction.

4.2.23.2 Removing default jobs

If the given job identifier responds to the default package/job, DMS has to delete all default posi-
tions/items (some DMS refer to that using an empty menuCode). Some DMS does not support pack-
ages and job levels, a cancelJob-request aiming at items of the default job must lead to removing all
default items of this default job in DMS.

4.2.23.3 Response orderDMS::cancelJobResponse

Figure 88 Structure of method response cancelJobResponse

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 135
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The response informs the calling client about the success of the cancellation (jobIdentifier given) or
errors. Note that errors relate to jobs because cancelJob may pass several jobs to be cancelled.
<cancelJobResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<jobIdentifier>103</jobIdentifier>
<jobIdentifier>104</jobIdentifier>
<error>
<errorCode>DMS-0810</errorCode>
<errorCategory>REJECT</errorCategory>
<errorDescription>blocked item</errorDescription>
<errorDescriptionLocal>blocked item: already clocked
in</errorDescriptionLocal>
<jobIdentifier>106</jobIdentifier>
</error>
<lastChangedDMSTimestamp>2010-10-17T11:10:00Z</lastChangedDMSTimestamp>
</cancelJobResponse>

4.2.24 Method orderDMS::printOrderBase (LF4)

With supported feature level LF4 an alternate printout can be triggered by method <printOrder-
Base> (see 4.2.24). Beside userInformation the order for printing (GUID, orderNumber) and print in-
structions must be given, as shown in Figure 89. Printer Instructions may contain a <printer> target
- allowed printers are returned by <getSetupValues>.

Figure 89 Structure of method printOrderBase (LF4)

<printOrderBase xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<userInformation>...</userInformation>
<order>
<GUID>GUID-324-84726</GUID>
<orderNumber>8472673</orderNumber>
<orderType>order</orderType>
</order>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 136
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<printInstruction>
<printJobCard>true</printJobCard>
<partsPickList>true</partsPickList>
<printer>
<uniquePrinterName>HP LaserJet</uniquePrinterName>
<printerDescription>Kopierraum (1. OG)</printerDescription>
</printer>
</printInstruction>
</printOrderBase>

4.2.24.1 Response orderDMS::printOrderBaseResponse

The method’s response informs the caller of errors and a new lastChangedDMSTimestamp (e.g. for
changed printing items in the pick list; this element must be returned in LF4):

Figure 90 Structure of method response printOrderBaseResponse (LF4)

<printOrderBaseResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="orderDMS" version="04.00.06"/>
<schemaRef refSchema="orderDMS" version="04.00.04"/>
<lastChangedDMSTimestamp>2001-12-17T09:30:47Z</lastChangedDMSTimestamp>
</printOrderBaseResponse>

4.3 XML data types

4.3.1 General
The field length of an XML element may be allowed by the XML scheme but too long for the corres-
ponding DMS field. In this case the DMS may truncate the field and is returns an error (category INFO)
in the response method. The error indicates which field has been truncated in the DMS.
If a truncation is critical for the DMS, the DMS may set the error category to REJECT and request the
user to shorten the input in ISPA.
The XML schemes define generic types that are used in several methods. Some of them need a de-
tailed explanation which is given in this section.

4.3.2 Type scoreDMSgeneric::typeSchemaVersionReference

This type represents the XML schema version.
Each method has an element <schemaRef> with type typeSchemaVersionReference. It gives
receiving systems the possibility to check version compliance.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 137
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 91: Structure of type typeSchemaVersion

If the combination of refSchema and version differs from the expected one, a fatal error is returned.

4.3.3 Type scoreGenericTypes::dealerType

An element of the type dealerType contains the information that authenticates ISPA against other IT
systems. The information is as documented in the BMW Group central dealer registry (German:
Händlerstamm).

Figure 92: Structure of dealertype

The content of warrentyDealerNumber is the business number (5 digits) (German: Business Num-
ber). It depends on the product channel (motorcycles or automobiles). It may be but need not be iden-
tical with the distribution partner number. This number is the unique identification of the dealer for
• the BMW parts contract of a dealer,
• the authentication for BMW AG backend systems and

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 138
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• for communicating warranty business by the BMW AG.

The content of distributionPartnerNumber identifies the distribution partner (5 digits) (German:
Vertriebspartnernummer).
The content of outletNumber is the number of the outlet of the distribution partner (2 digits) (Ger-
man: Betriebsnummer).

4.3.4 Type scoreGenericTypes::typeUserInformation

An element of type typeUserInformation contains Information about the ISPA user (Figure 93).
User information contains the information to log in into the DMS. The values are DMS site specific.
They are manually set in the ISPA system console by the ISPA administrator.
Some DMS systems use a generic user ID for all ISPA users. In this case a user ID is set in the ISPA
system console.
Some other DMS systems use the user name and password of the ISPA user to log into the DMS. In
this case no user ID and no password are set in the ISPA system console.
IMPORTANT: If the DMS uses the service advisors setup in ISPA, these service advisors must also
be set up in the DMS, i.e. the users send by ISPA must exist in the DMS.
For more details see the ISPA online help.

Figure 93: Structure of type typeUserInformation

Each request contains the following authentication and user information:
<userInformation>
<userID>raquel</userID>
<firm>Bavaria Motors</firm>
<branch>Avenida de Burgos</branch>
<language>es-ES</language>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 139
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<workplaceID>LMUC345123</workplaceID>
<password>secret</password>
</userInformation>
Sample 1 Listing of the user information
User ID and password can be user-specific (what the user entered upon starting ISPA) or centrally
configured, i.e. the same user ID and password for all workstations.

4.3.4.1 Authorization
Every user should be able to do the same work in ISPA that he/she may perform inside the native
DMS Client. The ISPA XML interface should neither open a backdoor nor offer only limited functionali-
ty.
• If a user only has permissions to deal with MINI, you‘ll have to filter <searchCustomerRes-
ponse> result sets accordingly.
• If a user may not create orders (role “Service Assistant”), <storeNewOrderBase> should be re-
jected for that user.

4.3.5 Type scoreGenericTypes::typeVehicleReference

Figure 94: Structure of a vehicle reference

4.3.6 Type scoreGenericTypes::typeVin

This type represents the vehicle identification number. There are two variants: short VIN with 7 digits
and long VIN with 17 digits (10+7 digits).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 140
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 95: Structure of vehicle identification number

 VINs may be 7 (short vin) or 17 (full vin) characters long. It’s important that the interface
understands both.
ISPA does not check the VIN, it treats it as a simple string.
ISPA is not performing any conversion to upper case characters.
 Be sure to cope with VINs that were entered in lower case. ISPA does not convert them to
upper case automatically.
 Make sure wrong VINs (not 7 or 17 digits long, containing invalid characters etc.) do not
crash the interface. If a typo makes a 7-digit VIN a 8-digit VIN, would the doublet detection in
the DMS recognize that this VIN already exits?

4.3.7 Type scoreGenericTypes::typeUnitValue

Figure 96: Values with units

A special case with the same structure is the typeMileage (Figure 97).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 141
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.8 Type scoreGenericTypes::typeMileage

Figure 97: Structure of mileage

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 142
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.9 Type scoreGenericTypes::typeCustomerResult

Figure 98: Structure of customer result (1)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 143
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 99: Structure of customer result (2)

The vehicle reference consists of the VIN, the number plate, the brand (optional) and the model desig-
nation (optional).
Note that not all customer/vehicle fields are returned but only those that belong to element groups with
name groupAaaResult. Also here the general convention applies that optional elements are only
present if they have content or they are explicitly empty.
Sample listing:

<searchCustomerResponse xmlns="http://www.bmw.com/score">
<schemaRef xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
refSchema="scoreDMSgeneric" version="04.00.06"/>
<resultSize>1</resultSize>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

 BMW Group Page 144
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

<customerResult>
<customerNumber>120014</customerNumber>
<lastName>Softlab GmbH</lastName>
<matchCode>SOFTLAB GMBH</matchCode>
<companyName>BMW International</companyName>
<branch>A</branch>
<address1>Zamdorfer Straße 120</address1>
<postCode>81677</postCode>
<city>München</city>
<firstName>Human Resources</firstName>
<telPrivate>089/9936-0</telPrivate>
<telCommercial>089/9936-1579</telCommercial>
<lastContactDate>2007-02-23</lastContactDate>
<customerIndicator>KD_INL</customerIndicator>
<creditIndicator>false</creditIndicator>
<lastChange>2007-02-23</lastChange>
<vehicleReference>
<vin>WBAAP71020PP38538</vin>
<numberPlate>M-VE 3300</numberPlate>
<brand>BMW</brand>
<modelDesignation>320d Touring</modelDesignation>
</vehicleReference>
</customerResult>
</searchCustomerResponse>

Sample 1 Listing of searchCustomerResult

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 145
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.10 Type scoreGenericTypes::typeCustomerDetail

Figure 100: Structure of customer detail

• Optional element flexFieldsCustomer is added (see section 4.2.1.7).
• The communication details are grouped in the element group groupCustomerCommunica-
tion (Figure 121).
• The company data to which the customer is assigned is grouped in the element group
groupCustomerAssigned (Figure 122).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 146
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.11 Type scoreDMSgeneric::typeVehicleDetails

Figure 101: Structure of vehicle details

• Optional element flexFieldsCustomer is added (see section 4.2.1.7).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 147
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• The vehicle production details are defined in the element group groupVehicleProduc-
tionDetails (Figure 127).
• The vehicle service details are defined in the element group groupVehicleServiceDe-
tails (Figure 128).

4.3.12 Type scoreDMSgeneric::typeFlatRatePriceRequest

Figure 102: Type typeFlatRatePriceRequest

4.3.13 Type scoreDMSgeneric::typePartPriceRequest

Figure 103: Type typePartPriceRequest

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 148
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 104: Type flatRatePriceEntry

4.3.14 Type scoreDMSgeneric::typePartPriceEntry

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 149
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 105: Type typePartPriceEntry

4.3.15 Type orderDMS::typeOrderBase (Read/Write) (LF4)

The order base is represented by an element of the type typeOrderBase (Figure 106).
• The group groupOrderHeader contains administrative information (Figure 25).
• The element serviceInformation contains the items catalog itself in the jobList (Figure
111).
• The customer ID of the DMS is given in the element customerNumber.
• The element <passingCustomerInformation> is present when the customer is marked
as a passing customer (section 3.6.3.2).
• References to external information resources like PuMA are stored in element <refer-
ences>.
• Element <destination> identifies the workshop destination of the order for dealers with
several branches (outlets).
• Element <flexFieldsOrderBase> is not yet used and reserved for future use.
• The element group groupKeyDerivedInfo is no longer transferred to the DMS. The group
contained several optional elements with information from the vehicle key. This information
was not used by the DMS and is therefore no longer supplied by ISPA.
The optional element <additionalText> is added in the element group groupInvariantOrder-
Header (Figure 106). Its content is a general note (header information for the order) on the order that
is created by the service advisor. The note shall be displayed on the respective DMS screen (section
3.6.16.1).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 150
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 106: Structure of the order base <typeOrderBaseRead> (LF 4)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 151
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 107 Structure of the order base <typeOrderBaseWrite> (LF 4)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 152
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.16 Type orderDMS::typeVehicle

Figure 108: Structure of the vehicle information within order base

4.3.17 Type orderDMS::typeJob (Read/Write) (LF4)

Type job has been splitted into typeJobRead and typeJobWrite in LF4. typeJobRead is for rea-
dOnly access (e.g. webservice responses) and typeJobWrite (e.g. see method addJob).
A job (<typeJob>) is composed of
• header data (jobIdentifier, jobDescription, jobComment)
• an optional customer statement (the element customerStatement must exist, but does not
need to have a content (section 3.6.6))
• optionally a part list with one or more parts

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 153
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• optionally a flat rate unit list with one or more flat rate units (FRU)
• optionally a package list with one or more packages (SRPs)
• the element group groupJobRow, which mainly carries information about an order split (sec-
tion 3.6.5) and a blocking state.
Positions of the workshop catalogue and 3rd party items appear as flat rate units in the job list. For
technical details see 4.3.17.
From delivery stage 4 type <typeJob> is self-contained and not a derived type. There exists 2 variants
for read and write access: typeJobRead and typeJobWrite.

Enhancement for SRP Monitoring with Version 4.0

In addition to the restrictions of the schemata the following rules have to be applied. For further re-
quirements to the DMS see [13], section “Anforderungen an andere Systeme” and the CR [14].
Note. It is possible that an xml schema is syntactical correct but operational not valid.

A job type must be specified. There are three possible job types:
1. BMW package: the job consists of one or more central packages defined by BMW AG
2. Dealer package: the job consists of one or more packages defined by the dealer
3. no package: the job has not got a package but one or more flat rate positions and an arbi-
trary numer of parts (zero is possible).
Note. A qualified statement customer and a qualified statement workshop has to belong to a job of job
type „no package“ and must have an assigned flat rate unit. This means there must not be a job with-
out an assigned flat rate unit or a package.

The job number, content of <jobIdentifier>, identifies the job and may not be changed by the
DMS when created. It is important that DMS do not change a jobIdentifier after creation. ISPA Client
will only change job numbers if they were updated by DMS after job creation in DMS (addJob).

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 154
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 109 Structure of type <typeJobRead> (LF4)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 155
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 110 Structure of type <typeJobWrite> (LF4)

4.3.18 Type orderDMS::typeJobList (Read/Write) (LF 4)

Jobs are packaged in JobLists for read and write access, represented by <typeJobListRead> and
<typeJobListWrite>:

Figure 111: Structures of the job list <typeJobListRead> und <typeJobListWrite> (>=
LF3)

4.3.19 Type orderDMS::typePart (Read/ Write) (LF4)

Like type orderBaseRead/Write part has readonly and write access type definitions: typePartRead and
typePartWrite.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 156
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

To integrate the parts clearing process which is introduced by the BMW program PPQ 9-1, an addi-
tional optional element <hasPartsClearing> is introduced. This flag indicates whether the part is
subject to a parts clearing, i. e. the BMW AG has to agree to a parts change for a warranty process.
The default is "false".
Part clearing is not introduced in all markets. Markets which use parts clearing shall print out the indi-
cation in the workshop order next to the respective part, flat rate or SRP provided that the flag is set to
"true".

Figure 112: Structure of typePartRead

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 157
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 113 Structure of typePartWrite

4.3.19.1 Fluid Parts

With LF4 element <isFluid> has been added to typeGenericPart and is therefore present in
typePartRead/Write. DMS should only set this flag if it knows that a part is fluid or not. Otherwise this
element can be ignored.

4.3.20 Typ orderDMS::typeSplitInformation (LF 4)

Used in groupOrderSplit and therefor in typePartRead/Write.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 158
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 114 Structure of <typeSplitInformation>

4.3.21 Type qualifiedStatement::typeCustomerStatement

Figure 115: Structure of customerStatement

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 159
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.22 Type orderDMS::typeFlateRateUnit(Read/Write)

(LF 4)
According to readonly and write access flatRateUnits are available as typeFlatRateUnitRead and
typeFlatRateUnitWrite. This type is derived from complex typeGenericFlatRateUnit.

Figure 116: Structure of typeFlatratUnitRead

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 160
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 117 Structure of typeFlatRateUnitWrite

4.3.22.1 Enhancement for SRP Monitoring with Version 4.0

Labor items from the ISPA workshop catalogue are mapped to FRUs when they are part of the order
base. In this case the value of the attribute number of the element flatRateUnit is set to
"ESTIMATE". This value indicates to the DMS that the item has been taken from the workshop cata-
logue. The DMS is expected to have corresponding work items to the positions of the workshop cata-
logue.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 161
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

3rd party items are mapped to FRUs when they are part of the order base. In this case the value of the
attribute number of the element flatRateUnit is set to "ISPA_SUBLET". This value indicates to
the DMS that the item is to be interpreted as a 3rd part labor or part.
To integrate the parts clearing process which is introduce by the BMW program PPQ 9-1, an additional
optional element <hasPartsClearing> is introduced. This flag indicates whether a part, which is
assigned to the FRU, is subject to a parts clearing, i. e. the BMW AG has to agree to a parts change
for a warranty process. The default is "false".
Part clearing is not introduced in all markets. Markets which use parts clearing shall print out the indi-
cation in the workshop order next to the respective part, flat rate or SRP provided that the flag is set to
"true".

4.3.23 Type orderDMS::typePackage (Read/Write) (LF 4)

Figure 118: Structure of typePackageRead (SRP) LF 4

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 162
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 119 Structure of typePackageWrite (LF4)

4.3.23.1 PackageType handling and isLocal flag

The element <packageType> identifies the type of the package and is used in conjunction with type’s
attribute isLocal. If a service repair package is modified by ISPA, its package type stays “SP”, but its
isLocal-flag is switched to TRUE. If a package is created manually (manual package), its type stays a
dealer package for its whole lifetime. <packageType> is set once during creation and is not changed.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 163
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.3.23.2 Enhancement for SRP Monitoring with Version 4.0

For packages, it must be specified who created the package. Therefore the creator, i.e. BMW (for
central packages), the NSC (NSC packages) or the dealer (for local packages) has to be declared.
In addition, the declaration of a package type is obligatory. Each package is classified according to
one of the following package types by a 3-character code:
• SRP service repair package
• SIP service package
• VLP value line package
• MRP marketing campaign package
• GRP warranty repair package
• CCP care and cosmetic package
• TCP technical campaign package
• PAP paint package
• ACP accessories package
• DLP manual package by dealer (it was not retrieved as a package from KSD)

In addition to the package type, some packages may have an optional package flag according to the
following table (the permitted combinations must be assured by the DMS):

Package flag Package type

value line marketing campaign package
fastlane All

Furthermore, a package must have a campaign number if it is a marketing campaign package.

The SRP Monitoring requires that each package has at least one flat rate position (labour) and that
one is marked as “lead labour”. The lead labour is the flat rate unit whose number is part of the pack-
age numer.
Besides, it must be possible to transmit defect information for a package. It contains the defect valid
for a flat rate, e.g. defect “87…” for a Service Inclusive package.
GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011
BMW Group Page 164
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Thus a package has got complex attribute defect information that holds the defect code and the defect
text.
For further information about how to set the attributes etc. see [13], section “Anforderungen an andere
Systeme”.

4.3.23.3 Enhancement in version 3.1.0

To integrate the parts clearing process which is introduce by the BMW program PPQ 9-1, an additional
optional element <hasPartsClearing> is introduced. This flag indicates whether a part, which is
assigned to the package, is subject to parts clearing, i. e. the BMW AG has to agree to a parts change
for a warranty process. The default is "false".
Parts clearing is not introduced in all markets. Markets which use parts clearing shall print out the indi-
cation in the workshop order next to the respective part, flat rate or SRP provided that the flag is set to
"true".

4.3.24 Type scoreGenericTypes::typePackageFlags (LF 4)

Figure 120 Structure of typePackageFlags (LF4)

4.4 XML Simple types

Some simple element tapes have been explicitly defined for the XML schemes (Table 6). The naming
is such that a type typeBranch is assigned to the element branch. For more details see the schema
definition.
Table 6: Defined simple types
simpleType typeBranch
namespace http://www.bmw.com/score

type typeVarchr_20

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 165
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

used by element typeUserInformation/branch

facets maxLength 20
whiteSpace collapse
annotation documentation
Name of the branch (Filiale) the user is currently working in
simpleType typeBrand
namespace http://www.bmw.com/score

type restriction of xs:string

facets enumeration BMW

enumeration MINI
enumeration RR
enumeration MOT
annotation documentation
Brand type
simpleType typeBrandOpen
namespace http://www.bmw.com/score

type xs:string

annotation documentation
Brand type open to corporate external brands. May contain values of typeBrand (corporate brands) or ohters defined by
the DMS

complexType typeCurrency
Namespace http://www.bmw.com/score

type Type extension of typeCurrencyBase

Attributes currency
(optional) value

annotation documentation
Currency amounts (three-character codes, e.g. “USD”, “EUR”)
simpleType typeCustomerNumber
namespace http://www.bmw.com/score

type restriction of xs:NMTOKEN

facets maxLength 120

annotation documentation
DMS specific customer number
simpleType typeFirm
namespace http://www.bmw.com/score

type restriction of xs:string

used by element typeUserInformation/firm

facets maxLength 30
whiteSpace collapse
annotation documentation
Name of the firm of the user
simpleType typeFlatRateNumber
namespace http://www.bmw.com/score

type restriction of xs:string

facets maxLength 40

annotation documentation
Flat rate number
simpleType typeGUID
namespace http://www.bmw.com/score

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 166
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

type xs:string

used by element typeOrderIdentification/GUID

annotation documentation
Globaly unique id of an car flow and order base, internal identifyer
simpleType typeInputIndicator
namespace http://www.bmw.com/score

type restriction of xs:string

used by attribute typeVin/@inputIndicator

facets enumeration K
enumeration M
annotation documentation
Indicates, where the data is from
documentation
german: "Eingabeindikator"
simpleType typePackageNumber
namespace http://www.bmw.com/score

type restriction of xs:string

facets maxLength 40

annotation documentation
Package number
simpleType typePartNumber
namespace http://www.bmw.com/score

type restriction of xs:string

facets maxLength 40

annotation documentation
Type for BMW and non BMW part number
simpleType typePercentage
namespace http://www.bmw.com/score

type restriction of xs:decimal

facets totalDigits 5
fractionDigits 2
annotation documentation
General percentage format
simpleType typeProductType
namespace http://www.bmw.com/score

type restriction of xs:string

facets enumeration motorcycle

enumeration car
annotation documentation
Production type
simpleType typeStatusOrder
namespace http://www.bmw.com/score

type restriction of xs:string

facets length 120

annotation documentation
Status of the orderbase, necassary for the status synchronization between car flow and order base status
simpleType typeUserID
namespace http://www.bmw.com/score

type restriction of xs:string

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 167
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

used by element typeUserInformation/userID

facets maxLength 100

whiteSpace collapse
annotation documentation
The login of the user who uses the system. This is only unique with a given firm parameter
simpleType typeVarchr_120
namespace http://www.bmw.com/score

type restriction of xs:string

facets maxLength 120

annotation documentation
Standard field length 120
simpleType typeVarchr_20
namespace http://www.bmw.com/score

type restriction of xs:string

used by element typeOrderIdentification/orderNumber

simpleType typeBranch
facets maxLength 20
whiteSpace collapse
annotation documentation
Standard field length 20
simpleType typeVarchr_40
namespace http://www.bmw.com/score

type restriction of xs:string

facets maxLength 40
whiteSpace collapse
annotation documentation
Standard field length 40
simpleType typeVarchr_60
namespace http://www.bmw.com/score

type restriction of xs:string

facets maxLength 60

annotation documentation
Standard field length 60
simpleType typeVinFlat
namespace http://www.bmw.com/score

type restriction of xs:string

facets maxLength 20
whiteSpace collapse
annotation documentation
VIN as flat String without prefix and vinShort
XML Schema documentation generated by XMLSpy Schema Editor http://www.altova.com/xmlspy

4.5 XML Element Groups

The following chapter lists element groups used in the interface.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 168
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.1 Group groupCustomerCommunication

Figure 121: Element group groupCustomerCommunication

4.5.2 Group groupCustomerAssigned

Figure 122: element group groupCustomerAssigned

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 169
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.3 Group groupCustomerLocation

Figure 123: Element group groupCustomerLocation

4.5.4 Group groupCustomerPerson

Figure 124: element group groupCustomerPerson

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 170
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.5 Group groupCustomerBackground

Figure 125: element group groupCustomerBackground

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 171
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.6 Group groupCustomerCategories

Figure 126: Element group groupCustomerCategories

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 172
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.7 Group groupVehicleProductionDetails

Figure 127: Vehicle production details (type typeVehicleProductionDetails)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 173
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.8 Group groupVehicleServiceDetails

Figure 128: Vehicle service details (type typeVehicleServiceDetails)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 174
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.9 Group groupOfferPriceEntry

Figure 129: Structure of prices in a price request

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 175
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.10 Group groupPriceEntry

Figure 130: Structure of prices in a price response

4.5.11 Group groupOrderHeader

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 176
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Figure 131: Order Header

The GUID (global unique identifier) is generated by a software component, triggered by ISPA. The
GUID identifies a service case and an order. It may not be changed by the DMS.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 177
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

The guide number has a string format since some dealers use guide numbers composed of letters and
digits. Note that GUID may be generated by storeNewOrderBase or updateOrderHeader.
The vehicle is of type typeVehicle and contains the relevant vehicle information (Figure 108).
The service advisor who is in charge of the service reception is passed in element <serviceAdvi-
sorID>. The ID is defined as an attribute of a service advisor in the ISPA system console. It must
exactly match the ID in the DMS.

4.5.11.1 Planned return date and service advisor for vehicle return
The service advisor, who is in charge of the return of the vehicle, and the planned vehicle return date
(day and time) are transmitted to the DMS. The data are printed on the workshop order and on the
invoice. This person can be different to the service advisor who has received the customer.
The service advisor in charge of for return of the vehicle is identified by the DMS through the content
of element <returnServiceAdvisorID>. The ID is defined as an attribute of a service advisor in
the ISPA system console. It must exactly match the ID in the DMS. If the vehicle is returned without a
service advisor the element is omitted.
The planned return date is mandatory in ISPA (element <plannedReturnDate>). The format is date
(day and time).

4.5.11.2 Dealer data to correctly create the order number

The element group groupOrderHeader contains a new optional element <dealerDetails> (see
below) with three subelements to define the company, the branch and the storage place. Some DMS
systems need this information to create order numbers correctly. These elements are optional. The
values are set in the ISPA system console. During the specification phase of an actual DMS interface
implementation decisions have to be taken as to how these attributes have to be exchanged.
The order of element <dealerDetails> was changed from version 3.0 to 3.01 to a position directly
after <dealer>. The element <plannedReturnDate> is changed from mandatory to optional in version
3.1.0.

4.5.12 Group groupDiscountedPrice

Figure 132: Structure of the customer specific Price (Detail)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 178
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.13 Group groupJobrow (order split information)

Figure 133: Structure of the order split information

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 179
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.14 Group groupOrderHeader (LF4)

Figure 134 Structure of Groups <groupOrderHeader> (including <groupInvariantOrder-

Header> in LF4)

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 180
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

4.5.15 Group groupOrderSplit

Figure 135 Structure of groupOrderSplit

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 181
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

5 Error handling
The structure of the error object has been altered by one minor change: the <errorCode> element is
now mandatory instead of optional. The error handling has been expanded in order to establish an
effective user support. An error catalog with error numbers and error descriptions has been defined.

5.1 Error structure

The structure of most response methods that the DMS sends to ISPA provides one or more error ob-
jects. These are generated by the DMS when an error occurs. The general structure of an error object
is shown in Figure 136.

Figure 136: General structure of an error

Sample 2 shows an example of a message that reports a fatal error.

<storeNewOrderBaseResponse xmlns="http://www.bmw.com/score"
xmlns:vis="http://www.bmw.com/scoreSchemaVisibility"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<schemaRef refSchema="orderDMS" version="04.00.03"/>
<GUID/>
<orderBaseErrors>
<error>
<errorCode>DMS-0200</errorCode>
<errorCategory>FATAL</errorCategory>
<errorDescription>The Arbeitswertemaster does not exist. fields and values:
='BMW',Nr.='0000646'</errorDescription>
<errorDescriptionLocal/>
</error>
</orderBaseErrors>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 182
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

</storeNewOrderBaseResponse>

Sample 2 Sample of a fatal error (storeNewOrderBaseResponse)

To allow the correction of input data the user has to determine the exact fields to correct. If the trans-
action data contains multiple rows, the error element has to determine the respective row. For that
reason the error is returned in a row structure with the logical key of the affected rows. Example: The
method createOrderBase may lead to errors on parts, flat rates etc. The response method crea-
teOrderBaseResponse then contains an error object for each erroneous item. If the response re-
turns a structure that already contains a row structure, errors can be returned in the row structure.

5.1.1 Hints
You have to return the error as an <error> object in XML. The XML schema for the different responses
is not always the same, so you need to check the schema before you define the error message.
Reason: There might be errors that are position-specific, (e.g. one part doesn’t exist, but others do)
• If you cannot even detect the XML root element, return a SOAP fault.
• HTTP Error Codes (like 500 Server Error, 501 Not Implemented, 503 Service Unavailable) are
not supported
• Errors may not be returned as HTML Pages

5.2 Error categories

Error descriptions are prepared to be displayed to the user. Additionally error codes can be returned
for support and diagnostic reasons. The behavior of ISPA on errors is determined by the error catego-
ry. There are three categories (Table 7).

Table 7: Error categories

Category Definition Example

FATAL The calling method has failed because of a failed ISPA broker error due to an incorrect XML
connection, an interface which is not available or of message
a software error. Support is necessary. DMS not running
REJECT The calling method has Customer data with an mandatory field
empty
• failed because of wrong user input or
Order base with no job defined.
• succeeded, the responding method,
A price is requested for an item with no
however, cannot deliver a certain re-
price assigned in the DMS.
quested information.
The availability is requested of a part that is
The description describes the reason in detail. The not known in the DMS.
method can be called again after correcting the
input.
INFO The calling method hat succeeded. The description Order opening was successful but the prin-
explains details of the processing, especially if it ter was not ready so automatic printing
differs from the regular case. didn’t work.

5.3 Error codes

The format of an error code is
DMS-xxxx
xxxx stands for a four digit decimal number. The numbers 0 to 0999 are reserved for BMW defined
error codes.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 183
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Table 8 lists the codes which are defined for ISPA delivery stage 2. More codes may be added in later
delivery stages. The DMS has to return these error codes to establish an effective user support sys-
tem.
The list of error codes is changed from version 3.0 to version 3.1.0. Errors that are related to the HTTP
connection and to the ISPA broker rather than the DMS system have been removed.

New LF4 related error codes (DMS-08xx) have been added to the following table:
Table 8: List of DMS error codes

Code Cate- Description XML method Subelement of

gory respectively ele-
ment type

General

DMS-0000 FATAL DMS interface version %re- all methods

ceived_version_number% is not
supported. Request %send re-
quest% failed because of %er-
ror_message%. Interface version
currently supported is %cur-
rently_supported_version%

DMS-0001 FATAL login to DMS failed for technical all methods

reasons3

DMS-0002 FATAL language not supported all methods typeUserInformation

DMS-0003 FATAL broker request is not interpretable all methods

(no XML)

DMS-0004 FATAL unknown request (function not all methods

supported)

DMS-0005 FATAL invalid or not interpretable field all methods

content

DMS-0006 FATAL Login to DMS failed: Invalid all methods typeUserInformation

workplace

DMS-0007 FATAL Login to DMS failed: Invalid com- all methods typeUserInformation
pany name

DMS-0008 FATAL Login to DMS failed: Invalid all methods typeUserInformation

branch identifier

DMS-0306 INFO field lengths do not match, field all methods

content truncated

Setup values and authentication

DMS-0300 FATAL User authentication not valid4 most methods typeUserInformation

DMS-0310 FATAL Error in retrieving setup values getSetupValues

Customer and vehicle information

3 e.g.: Too many open sessions of this user at the same time
4 i.e.: Wrong password or unknown user name
GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011
BMW Group Page 184
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Code Cate- Description XML method Subelement of

gory respectively ele-
ment type

DMS-0400 REJECT unknown service advisor addCustomer,

changeCustomer,
storeNewOrder-
Base

DMS-0401 REJECT invalid VIN (e. g. more than 17 most methods5

digits)

DMS-0402 REJECT vehicle type not found many methods

DMS-0403 REJECT Customer not known getCustomerDe-

tails

DMS-0404 REJECT Combination customer and vehi- getCustomerDe-

cle invalid tails

DMS-0405 REJECT Unable to add customer to DMS addCustomer

database

DMS-0406 REJECT Unable to change/update cus- changeCustomer

tomer in the DMS database

Work items and parts

DMS-0500 REJECT Unknown flat rate unit getPriceInforma- flatRateUnitPrice

tionResponse

DMS-0501 REJECT Unknown service and repair getPriceInforma- packagePrice

package tionResponse

DMS-0502 REJECT Part not known getPriceInforma- typePartPriceEntry

tionResponse

DMS-0503 REJECT Part not in dealer database checkPartsAvail- typePartAvailability

abilityResponse

DMS-0504 REJECT Unable to retrieve local FRU data getLocalFla-

tRateGroupList,
getLocalFla-
tRateGroup, get-
LocalFlatRateDe-
tails

DMS-0505 REJECT Unable to retrieve local SRP data getLo-

calSRPGroupList,
getLo-
calSRPGroup,
getLocalSRPDe-
tails

Orders

5Note: getPriceInformation and checkPartsAvailability cannot reject a request if a wrong or no VIN is

specified. In this case the default VIN should be used. In storeNewOrderBase and
add/changeCustomer only vehicles with brand={BMW|MINI|RR|MOT} should be checked for validity.
Other makes should not be checked, as there will not be any VIN range definition file to check against.
GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011
BMW Group Page 185
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

Code Cate- Description XML method Subelement of

gory respectively ele-
ment type

DMS-0600 REJECT Order creation not possible be- storeNewOrder- typeOrderBaseEr-

cause of unknown flat rate unit BaseResponse rors

DMS-0601 REJECT Order creation not possible be- storeNewOrder- typeOrderBaseEr-

cause of unknown service and BaseResponse rors
repair package

DMS-0602 REJECT Order creation not possible be- storeNewOrder- typeOrderBaseEr-

cause of unknown part BaseResponse rors

DMS-0603 REJECT Unknown cost center for order storeNewOrder-

split BaseResponse

DMS-0604 REJECT Unknown account for order split storeNewOrder-

BaseResponse

DMS-0605 REJECT Unknown customer for order split storeNewOrder-

BaseResponse

DMS-0606 INFO Order printout (job card) failed storeNewOrder-

BaseResponse

DMS-0607 INFO Order printout (parts pick list) storeNewOrder-

failed BaseResponse

DMS-0608 REJECT Order with given number not getOrderDetails

found

DMS-0609 REJECT Invalid date getOrderList

Job Errors (since LF4)

DMS-0801 REJECT Reject adding a job because a addJobResponse

blocked flatrate cannot be de-
leted.

reserved for enhancements

DMS-0800 -
DMS-0999

The numbers 1000 to 9999 are specific for a DMS and defined by the DMS itself. ISPA will display
these errors.

5.3.1 Hints
• Use DMS-1000 and up for your own error codes.
• Include a list of your own error codes in the Release Notes that you provide to our support and
include a hint what they should do if they encounter it.
• The XML also includes <errorDescription> and the optional <errorDescriptionLocal> .
• <errorDescription> should be in English, and <errorDescriptionLocal> in the language of the
user.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 186
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

• If <errorDescriptionLocal> is present, we’ll display it. If it’s not there, ISPA Client will show
<errorDescription> to the user.

5.4 Error display in ISPA

ISPA shall display errors of the categories FATAL and REJECT in a message box with all information
(number, category, description). It is likely that the ISPA support is called when an error of these cate-
gories occurs.
ISPA displays the error code and the local description (element errorDescrptionLocal). If to ele-
ment errorDescrptionLocal is available, ISPA displays the English description (element error-
Descrption).
Errors of the category REJECT, which are triggered by missing data in the DMS, currently often are
displayed as a red bullet with a red x within. The tooltip shows the language specific description
(Figure 137).
INFO errors shall as far as possible be displayed in the status line. The user does not want to "click
away" simple message boxes.

Display of messages of category REJECT

Figure 137: Display of messages of category REJECT for specific fields

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 187
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

6 Technical Interface Description

6.1 Communication technology

The communication technology between ISPA and the DMS is SOAP / HTTP.

6.2 XML Schemes

The XML schemes are listed in section 2.3.1. As far as the structure of the schemes is concerned the
following is important:
The element sequence that is defined in the XML schemes cannot be changed even though the
schema’s rules do allow that in some cases. ISPA cannot deal with an element sequence that is
different from the sequence set in the schemas.

6.3 Authentification and authorization

See typeUserInformation (see 4.3.4).

6.4 Performance requirements and load tests

This section lists the performance requirements which ISPA demands from the DMS interface. For
details about the test procedure, the test environment and the test tools see the ISPA-DMS Interface
Implementation Guide [1]. The performance tests are executed under laboratory conditions.
The performance time is the time interval from the sending of a request by ISPA until the receiving of
the response in ISPA.
Table 9: Performance requirements for interface methods

Method Time [s]

searchCustomer (100 hits) 3,00
searchCustomer (0 or 1 hit) 0,50
getCustomerDetails 1,00
addCustomer 1,00
changeCustomer 1,00
getLocalFRUGroupList 0,50
getLocalFRUGroup 0,50
getLocalFRUDetails 0,50
getLocalSRPGroupList 0,50
getLocalSRPGroup 0,50
getLocalSRPDetails 0,50
getLocalPartDetails 0,50
checkPartsAvailability 0,05
getPriceInformation (1 part or 1 FRU position) 0,05
getPriceInformation (10 SRPs with several 0,50
items each)
storeNewOrderBase 1,90
checkOrderBaseStatus 0,10
getOrderBase 1,90
updateOrderHeader 1,50
addJob 1,00
cancelJob 1,00

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 188
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

printOrderBase 1,50
resetOrderChangeFlag 0,50

6.5 Version Lookup

The version lookup feature has been introduced to manage different interface version on 2 or more
systems. The idea is that a system (i.e. the DMS) tells ISPA which version(s) of the interface are cur-
rently supported. Based on this information ISPA can then deal with it (send it on, transform it etc.).
The ISPA supports communication to DMS with the current schema and transformation to previous
schema versions. To identify the schema version supported by the DMS the broker sends a ver-
sionLookup message. In the versionLookup response the DMS lists the supported schema, version
and services. This response is mandatory for schema version 3 and higher. If the versionLookup mes-
sage is not responded, the broker assumes, that version 2.2 is supported and will send all messages
in that version.
The relevant XML scheme which contains the version lookup request is versionLoo-
kup_v01.00.02.xsd
Please note: Several other components implement this service, in the case of the DMS Interface the
<supportedMarket> element should be left empty.
The version lookup should return the schema with version and a list of supported methods.
Table 10: Structure of the method versionLookup

Structure Description
schema / name Name of the schema
schema / version Supported Version of the schema
service / name List of supported methods

The structure is a subset of a more general version lookup structure covering multiple schemas and
service restrictions.
The versionLookup message is repeated periodically until a first message of any kind is answered by
the DMS.
The testdriver is included in the broker and uses the broker to communicate. During startup of the
broker the versionLookup request is sent from the broker to the DMS.
After that the testdriver may be used to send other requests to the DMS. To trigger the versionLookup
it is necessary to restart the broker (e.g. startBroker.bat or RunScoreBrokerService.cmd).

6.6 Logging
Correction from version 3.0 to version 3.01
ISPA provides a logging service to support cross component logging for all involved components. This
interface should be used to log technical problems blocking the component from functioning properly.
The logging service can be accessed on:
http://<<ISIS_IP>>:8095/score_broker/servlet/logmessagerouter
The relevant XML scheme which contains the logging request is logger_V01.07.00.xsd.
For better diagnostics support all log entries are assigned to the originating client. ISPA sends the
clientID as a SOAP header field with each request. This client ID has to be passed to the logging ser-
vice.
The communication protocol is SOAP / HTTP.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 189
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

6.7 Connection Detection

The Broker recognizes connection problems by sending additional test requests after a communication
timeout. The test request is a HTTP GET to the soap endpoint. The request must be answered with
code 200 OK. If the test request is not answered correctly the DMS is assumed being down and no
further messages are sent to it. The test request is repeated periodically. When it is answered cor-
rectly the DMS can receive new messages.
If the DMS does not implement the HTTP GET, the feature is not available. The broker sends one test
request to find out if it is implemented.
In the context of the definition of ISPA Basic (ISPA running without a DMS) a criterion has been devel-
oped whether an ISIS is running in the "ISPA Basic" mode or the "ISPA Advanced" (ISPA running with
a DMS interface). ISPA Basic answers like a DMS. Therefore it is important to recognize whether a
test stub or a real DMS is answering to an ISPA request.
The ISPA broker 5.0.1 addresses the issue as follows. The synchronizer regularily requests the state
of orders in the DMS with the method checkOrderBaseStatus. It the synchronizer asks for an order
with the GUID XXX_CHECK_ISPA_STANDALONE_MODE, it expects a specific error message. If exac-
toy this one is returned, ISPA broker and ISPA services know that the ISIS is running in the "ISPA
Basic" mode.
It is relevant for the DMS configuration to know that there are regular requests for an order which does
not exist. The authentification will be correct in no case, so every DMS will deny this request, but with
a different error message than ISPA expects it. The only risk is the error log would get an overflow.
Therefore it is important for the DMS party to know this behaviour.
The regular request looks like this:

<?xml version="1.0" encoding="UTF-8"?><checkOrderBaseStatus

xmlns="http://www.bmw.com/score <http://www.bmw.com/score> ">
<schemaRef refSchema="orderDMS" version="04.00.03"/>
<userInformation>
<userID>userid</userID>
<firm>firm</firm>
<branch>branch</branch>
<language>de-DE</language>
<workplaceID>workplace</workplaceID>
<password>***</password>
</userInformation>

<dealer distributionPartnerNumber="12345" outletNumber="01" warrantyDealerNum-

ber="12345"/>

<orderIdentification>
<GUID>XXX_CHECK_ISPA_STANDALONE_MODE</GUID>
<orderNumber>orderNumber</orderNumber>
</orderIdentification>
</checkOrderBaseStatus>

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 190
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

7 Content of delivery
With implementing an interface to ISPA tat adhers to this interface contract every DMS has to provide
a document with Release Notes to ISPA in English language.
It should contain:
• Required hardware and software environments
• Instructions on how to set up the interface
• Functional and technical requirements to dealer environment
• Additional or product-specific error states and codes including descriptions and support hints
(e.g. order data printing behaviour)
• Mapping of customer and vehicle data between the interface and the DMS
• Functionality that was omitted, known limitations (e.g.: “Order split can only be 100% or 0%”)
• Additional blocking reasons

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 191
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

8 Change Log
Starting with version 3.1.1 of this document, a change log is introduced from one version to the next
one.

8.1 Changes from version 3.1.0 to version 3.1.x

Table 11: Changes from version 3.1.0 to version 3.1.x
No. Version Topic Description Section in Task in XML
GIC scheme
1 3.1.1 Flexfields Data type and value lists of flexible section <none>
fields are described more precisely. 3.4.4.2

1 3.1.1 Dealer indivicual Method checkPartsAvailybilityRe- section 3.2.8 Update in

parts (DIP) sponse: a mandatory element <isLo- scoreDMSGeneric
cal> of type boolean is added. If the _v03.01.01.xsd
part is a DIP, the value of the element
is "true", else "false".
2 3.1.1 Change Element <flatRateUnitType> is not section Update in
getLocalFlatRateD needed and not senseful. Delete. 3.2.2.2, scoreDMSGeneric
etailsResponse 3.2.5.2 _v03.01.01.xsd

3 3.1.1 Change Correct type of element <pack- section Update in

getLocalSRPDetai ageType> to typePackageType (Enu- 3.2.2.3 scoreDMSGeneric
lsResponse meration with values (SRP | MRP | _v03.01.01.xsd
GRP))
4 3.1.1 Change of In the method getCustomerDetails, the section 3.1.6 Update in
getCustomerDetail customer number is mandatory and scoreDMSGeneric
s the VIN is optional. Within the context _v03.01.01.xsd
of the intrduction of a Passing Cus-
tomers, a getCustomerDetails would
not work, since a Passing Customer
does not possess a customer number.
To ensure the consistency (seen from
the DMS), however, also the call of
getCustomerDetails must be possible.
Especially in the case if the Passing
Customer gets the state of a regular
customer in the DMS afterwords.
Especially at ADP this is the normal
case. The Core Component ISPA has
to follow the rules:
a) If constomer number and VIN are
known --> both data must be supplied.
b) If either customer number or VIN
are not known -> the known informa-
tion must be supplied.

-> Element <customerNumber> op-

tional instead of mandatory
-> Return also VIN in methode get-
CustomerDetailsResponse
5 3.1.1 Change It is required from the view of the section 3.1.8 <none>
changeCustomer DMS:
1. changeCustomer only if there is a
change
2. changeCustomer containing only
the changed fields
3. see defect 630
This meets a proper interface design.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 192
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

No. Version Topic Description Section in Task in XML

GIC scheme
6 3.1.1 Change Since in one getCustomerDetails section 3.1.6 Update in
getCustomerDetail request now several customers may scoreDMSGeneric
sResponse be found, the customer data (<cus- _v03.01.01.xsd
tomerNumber>, <customerDetails>
shall be wrapped in an additional
element <customer>. So it will be no
more necessary to process the re-
quest sequentially.
7 3.1.1 Version lookup Update, information added section 6.5 <none>

8 3.1.1 Connection Added section 6.7 <none>

detection

9 3.1.2 New element for Method storeNewOrderBase: Ele- section Update in or-
order creation ment <additionalText> added in 3.6.3.1, derDMS_v03.01.0
the order header, shall appear on the 3.6.16.1 2.xsd
DMS screens. Furthermore the infor-
mation can be printed out on the
workshop order.
10 3.1.3 New attributes New attributes for SRP Monitoring are
(retail net) price,introduced to the job list.
job type, lead
labour, package
type, package
flags isValueLine
and is Fastlane,
campaign number,
defect information
11 3.1.4 - Overview: New Job management for Merged schemas;
orders Updates in
scoreDMSGeneric
_v03.09.xx.xsd
and or-
derDMS_v.3.09.xx
.xsd
12 3.1.4 New Element Introduced for DMS/ISPA Client or-
lastChangedTime- date/time matching on add- derDMS_v.4.00.xx
stamp ing/cancelling Jobs/update order .xsd
headers/ finalizing orders.

13 3.1.4 Method addJob Method addJob/addJob or-

derDMS_v.3.09.xx
.xsd

14 3.1.4 Method cancelJob Method <cancel- or-

Job>/<cancelJobResponse> to derDMS_v.4.00.xx
abort. .xsd

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 193
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

No. Version Topic Description Section in Task in XML

GIC scheme
14 3.1.4 Method re- Method <releaseOr- or-
leaseOrder der>/<releaseOrderResponse> derDMS_v.4.00.xx
finalizes an DMS order .xsd

15 3.1.4 Method printOr- Method <printOrder- or-

derBase Base>/<printOrderBaseRespons derDMS_v.4.00.xx
e>: printing can be triggered before .xsd
storeNewOrderBase/finalizeOrder by
calling this method.

16 3.1.4 Method updateOr- Method <updateOrder- or-

derHeader Header>/<updateOrderHeaderRespon derDMS_v.4.00.xx
se> for header updates in DMS or- .xsd
ders.

17 3.1.4 New Element Method update. or-

<lastChanged- derDMS_v.4.00.xx
timestamp> in .xsd
<getOrderBaseR-
esponse>

18 3.1.4 New Types

<typeOrderType>,

19 3.1.4 New mandatory ISPA Client can obtain printer informa- scoreDMSGeneric
Element tion from DMS. _v04.00.xx.xsd
<printerList>
in Method <get-
SetupValues-
Response>
20

Detailed change log information can be found in schema files.

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 194
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

9 List of open items and future developments

The following items from the generic interface contract are open (Table 12).
Table 12: Open items and future developments

No. Description Deadline Responsible

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 195
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

10 Abbreviations
CBS Condition based service
DIP Dealer individual part
DMS Dealer management system
EPC Electronic parts catalog
FBM Fahrzeugbeschreibungsmodul (vehicle description module)
FRU Flat rate unit
GUID Global unique identifier
ISIS Integrated Service Information Server
ISPA Integrated Service Processes Application
LAN Local area network
LF Delivery Stage
KSD Commercial service data (Kaufmännische Servicedaten)
LF Delivery stage (Lieferstufe)
SOAP Simple object access protocol
SRP Service and repair package
VIN Vehicle identification number
VIN7 Vehicle identification number (7 digits)
WSDL Web Service Description Language
XML Extended Markup Language
XSD XML schema file

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011

BMW Group Page 196
Generic Interface Contract ISPA – DMS – via ISPA Broker v4.0 of 196

11 References
[1] Piotrowski, C.; vom Ende, A.: ISPA - DMS Interface Implementation Guide. How to implement,
test and approve an DMS interface to ISPA. Version 0.1. BMW VS-41, February 2007
[2] Piotrowski, C.: BMW Service 2008. Interaction between ISPA and a DMS. BMW Group VS-41,
Januar 2007
[3] XML schemes: scoreDMSgeneric_v03.01.01.xsd, orderDMS_v03.01.02.xsd, scoreGeneric-
Types_v03.01.00.xsd
[4] Piotrowski, C.: vom Ende, A.: Project ISPA: Test cases DMS interface generic. BMW VS-41,
November 2006
[5] Piotrowski, C.: vom Ende, A.: Projekt ISPA: Testfälle DMS Schnittstelle generisch. BMW VS-41,
November 2006
[6] vom Ende, A.: Entry and Exit Criteria for the Gateway of the interface ISPA-DMS. Version 0.1.
BMW VS-41, February 2007
[7] vom Ende, A.: Eingangs- und Ausgangskriterien für den Integrationstest der ISPA-DMS Schnitt-
stelle. Version 0.1. BMW VS-41, February 2007
[8] Tost, M. et al.: System Proposal Core Components of Core Component of Score, delivery
phase 1. Version 1.0. BMW Group VS-41, February 2006
[9] Tost, M. et al.: Fachkonzept Kernkomponente Score, Lieferstufe 1. Version 1.1 (in German).
BMW Group VS-41, April 2006
[10] Zierl, H.: ISPA Manual for the Technical Administrator. BMW Group, February 2007
[11] Zierl, H.: ISPA Support-, Betriebs- und Wartungskonzept. Version 1.0 (in German). BMW
Group, October 2006
[12] XML scheme: workshopStatement_v01.01.00.xsd

[13] Dirk Engelien, Sanja Faltermeir, Ulrich Heitmann, Friedrich Rössler, Arnold vom Ende, Julia
Bergsteiner, Joachim Wehler - Cirquent GmbH : SRP Monitoring Fachkonzept Version 1.1.
BMW Group VH-332, April 2010
[14] Oliver Schnier: Change Request – CR DMS from SRP Monitoring – 2010, Version 1.0, BMW
Group VH-332, März 2010
[15] ISPA 04.00.06 CR “VFC”
[16] ISPA 04.00.06 CR “Order Extension”

GIC ISPA - DMS via ISPA Broker V4.0.8.docx 09.08.2011