Sie sind auf Seite 1von 54

LinqUs Provisioning Manager

Command Parameters Reference Guide


All information herein is either public information or is the property of and owned solely by Gemalto NV.
and/or its subsidiaries who shall have and keep the sole right to file patent applications or any other kind
of intellectual property protection in connection with such information.
Nothing herein shall be construed as implying or granting to you any rights, by license, grant or
otherwise, under any intellectual and/or industrial property rights of or concerning any of Gemalto’s
information.
This document can be used for informational, non-commercial, internal and personal use only provided
that:
 The copyright notice below, the confidentiality and proprietary legend and this full warning
notice appear in all copies.
 This document shall not be posted on any network computer or broadcast in any media and no
modification of any part of this document shall be made.
Use for any other purpose is expressly prohibited and may result in severe civil and criminal liabilities.
The information contained in this document is provided “AS IS” without any warranty of any kind. Unless
otherwise expressly agreed in writing, Gemalto makes no warranty as to the value or accuracy of
information contained herein.
The document could include technical inaccuracies or typographical errors. Changes are periodically
added to the information herein. Furthermore, Gemalto reserves the right to make any change or
improvement in the specifications data, information, and the like described herein, at any time.
Gemalto hereby disclaims all warranties and conditions with regard to the information contained
herein, including all implied warranties of merchantability, fitness for a particular purpose, title
and non-infringement. In no event shall Gemalto be liable, whether in contract, tort or otherwise,
for any indirect, special or consequential damages or any damages whatsoever including but not
limited to damages resulting from loss of use, data, profits, revenues, or customers, arising out
of or in connection with the use or performance of information contained in this document.
Gemalto does not and shall not warrant that this product will be resistant to all possible attacks
and shall not incur, and disclaims, any liability in this respect. Even if each product is compliant
with current security standards in force on the date of their design, security mechanisms'
resistance necessarily evolves according to the state of the art in security and notably under the
emergence of new attacks. Under no circumstances, shall Gemalto be held liable for any third
party actions and in particular in case of any successful attack against systems or equipment
incorporating Gemalto products. Gemalto disclaims any liability with respect to security for
direct, indirect, incidental or consequential damages that result from any use of its products. It is
further stressed that independent testing and verification by the person using the product is
particularly encouraged, especially in any application in which defective, incorrect or insecure
functioning could result in damage to persons or property, denial of service or loss of privacy.
© Copyright 2009 Gemalto N.V. All rights reserved. Gemalto, the Gemalto logo, GemXplore and
Xxpress Campaign Technology™ (XCT™) are trademarks and service marks of Gemalto N.V. and/or its
subsidiaries and are registered in certain countries. All other trademarks and service marks, whether
registered or not in specific countries, are the property of their respective owners.
GEMALTO, B.P. 100, 13881 GEMENOS CEDEX, FRANCE.
Tel: +33 (0)4.42.36.50.00 Fax: +33 (0)4.42.36.50.90

Printed in France. Document Reference: LPMCPRG02


July 6, 2015
Contents

Preface ..................................................................................................................................... iv
For More Information ............................................................................................................. iv
Contact Our Hotline ............................................................................................................... iv

Command Syntax .................................................................................................................... 1


Create Subscription ............................................................................................................... 2
Update Subscription ............................................................................................................... 8
Change MSISDN.................................................................................................................. 13
Smart Change MSISDN ....................................................................................................... 14
Change SIM card ................................................................................................................. 16
Delete Subscription .............................................................................................................. 18
Get Subscription Information ............................................................................................... 19
Get Subscription Information Response .............................................................................. 20
Create Subscription 4AP ...................................................................................................... 24

The SOAP API ........................................................................................................................ 29


Architecture and Description ................................................................................................ 29
SOAP API Request Life Cycle ............................................................................................. 30
LPM SOAP Operations syntax............................................................................................. 30
Login/logout Operations – Token Usage ............................................................................. 31
Token Characteristics .......................................................................................................... 31
Properties File Usage – Filename........................................................................................ 32
Provisioning Operations ....................................................................................................... 32
SOAP API Scenario – Templates and Examples ................................................................ 35

Batch Files.............................................................................................................................. 44
Using the Batch connector ................................................................................................... 44
Batch reports ........................................................................................................................ 45

Error Messages ...................................................................................................................... 47


Preface

Preface

Gemalto LinqUs Provisioning Manager is part of LinqUs Over-The-Air Suite, a fully-integrated


software solution providing a robust, reliable and scalable infrastructure with which to manage
your (U)SIM installed base. LinqUs Over-The-Air Suite allows you to:
 Deliver new applications directly to your subscribers
 Easily adapt your service portal for diverse subscriber types
 Control your subscribers' mobile environment.

The role of LinqUs Provisioning Manager is to manage the (U)SIM and the associated related
data, by offering a set of provisioning commands to manage their life cycle:
 Subscription creation
 Subscription update
 Subscription end of life

LinqUs Provisioning Manager offers three interfaces for provisioning:


 A Web-based HTML Customer Care Interface to operate and administer the application
 A set of Web Services, to easily integrate the application with the operator’s back-end
operations
 A batch file interface for mass provisioning.

This guide provides information about Commands, Web services and Batch files' format and
usage.

For More Information


For more information on LinqUs Provisioning Manager, see the following documents:

Document Description
Installation Guide Describes the prerequisites and procedures for installing LinqUs
Provisioning Manager
User’s Guide Shows how to perform tasks using the Customer Care Interface (CCI).
Administration Guide Describes how to administer the product. Also includes log file, audit trail
and billing ticket formats, SNMP traps and counters, product parameters,
and error messages.

Contact Our Hotline


If you do not find the information you need in this manual, or if you find errors, contact the
Gemalto hotline at http://support.gemalto.com/.

iv
Preface

Please note the document reference number, your job function, and the name of your
company. (You will find the document reference number at the bottom of the legal notice on
the inside front cover.)

v
1

Command Syntax

This chapter describes the standard provisioning commands of LinqUs Provisioning Manager. These
commands can be used for both unitary and batch provisioning.

Note: In the parameter descriptions that follow, parameters can be:


 Mandatory: The parameter must always be supplied
 Optional: The parameter is optional
 Conditional: The parameter is mandatory if an optional parameter is supplied

Color keys used in the examples that follow


iccid="" xml LPM command or command response information
"SMS" Example of value
Specific datas for non targeted products.
2 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Create Subscription
This command creates a subscription in any available product present in the configuration, with specified
input parameters. The OTA Manager product must be installed.

Parameters
The command accepts the following parameters:

Parameter Type Description

ICCID Mandatory The ICCID of a new SIM card.


<CreateSubscription iccid="" …

IMSI Mandatory The IMSI of a new SIM card.


<CreateSubscription imsi=""… in classic
provisioning

Optional in
NG
provisioning
with SPS

MSISDN Optional The phone number of the new subscription, usually


<CreateSubscription msisdn =""… not known at the personalization stage.
Mandatory if the initial State is ACTIVE

Initial State Mandatory ACTIVE, INACTIVE


<CreateSubscription
initialState=""…

OTA Manager-specific

Card Profile Mandatory Associate the card with an electrical profile (a set of
<CreateSubscription files and applets loaded during the personalization
cardProfile=""…
stage).

Group identifiers Optional Add the card to one or more groups.


<CreateSubscription groupId=""…
Defining multiple group can be done by using pipe (|)
separator

For example:
groupId="group01|group04"

2
3

OTA security Optional Create Security domains and OTA keys.


Providing OTA security is not mandatory in the
Create Subscription command, but it is generally
<CreateSubscription …> mandatory to update the card after issuance.
… This parameter contains the complete security
<Ota-security> definition for the card:
<MBCard serialNumber="must
contain iccid value">
 MBCard defines card security information

(MBcardModule is invalid and should not be
defined in Ota-security).
</MBCard>
 List of synchronization counters (IDs and values)
</Ota-security>
 For 03.48 cards, a list of security domains (ID,

default synchronization counter value, key sets,
</CreateSubscription>
and so on)
 For native cards, a list of security key files.
 The transportKey and algoName attribute must
be specified in the MBCard level or lower level
such as SecurityDomain, SecurityData or key
level.
Refer to the OTA Manager Provisioning Guide for
more details on security provisioning.

Device Manager-specific
<CreateSubscription imei=""…>
Optional

<Handset>
<Model …/>
<Groups>

</Groups>
<SubscriptionList>

</SubscriptionList>
<ServiceConfigurations>
<Service …>

</Service>
</ServiceConfigurations>
</Handset>

</CreateSubscription>

IMEI Optional Unique International Mobile Equipment Identifier


<CreateSubscription imei=""… (IMEI) of the subscriber’s handset.

Handset.model.manufacturer Optional The subscriber’s handset manufacturer.


<Model manufacturer="LG"…

3
4 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Handset.model.name Optional The subscriber’s handset model.


<Model … name="U300"/>

Handset.Groups.Group.name Optional List of handset groups, for example, “PostPaid”.

Handset.SubscriptionList. Optional List of handset service names, for example, “EMAIL”.


Subscription.Service

Handset.ServiceConfiguration Optional List of subscription services to configure.

 Service:  For each service:


 Type  Type of handset service, for example EMAIL
 Configured  True or False
 Default  True or False
 GenericParameters.name  Name of generic parameters
 UserDependentParameter  List of user-dependent parameters
 Characteristics.type  Type of characteristics
 Parameter  List of parameters:
Name Name of the parameter of a user-dependent
parameter
Value Value of the parameter of a user-dependent
parameter.
Service Manager-specific
<ServiceContent> Optional
<Portal>
<Perso label="test"
majorVersion="1"
minorVersion="0"/>
</Portal>
</ServiceContent>

ServiceContent.Portal.perso.label Optional Label of portal defined during the card


<Perso label="test"… personalization phase. The Perso portal must be
declared in the Service structure of the Service
Manager and linked to the OTA card profile

Conditional Major version of personalization portal. Can be


ServiceContent.Portal.perso.major
Version defined only if a label is specified. If no version is
specified, SM chooses the most recent portal (with
majorVersion="1"
the highest version).If only major version is supplied,
LPM sets minor version to 0.
ServiceContent.Portal.perso. Conditional Minor version of personalization portal. Can be
minorVersion defined only if a label is specified.
minorVersion="0"/>

ExecScript
ServiceCallProtocol Optional Whether to use the SMS or CAT-TP (BIP) protocol
<CreateSubscription when calling services. If no value is specified, the
serviceExecutionProtocol="SMS" default value is taken from the OTA_PROTOCOL
product parameter.
Script Optional The script to execute, specified as a string.
<ExecScript>
public class MyScript
Refer to the OTA Manager Script Programming
{...
Guide for script syntax.
}
</Execscript>

Subscriber Repository Manager-specific

4
5

<SubscribeTo> Optional Capabilities and options for subscriptions.


<Capabilities>
<Capability key="Prepaid"
value="false"/>
</Capabilities>
<SubscribedOptions>
<SubscribedOption name="NFC"
state="ACTIVATED"/>
</SubscribedOptions>
</SubscribeTo>

SE-KMS-specific
Secure Element Optional Information of Secure Element to be created in SE-
<SecureElement> KMS. It contains only CACertificate information. The
<DomainName>Domain_Name</Domai domain name and CACertificate are required.
nName>
<CACertificate>FF1122…</CACert
ificate>
</SecureElement>

Sekms Data Optional Information of Secure Element to be created in


<Sekms-data> SEKMS. It contains provisioning data of SEKMS in
<![CDATA[<gsepml:ExecuteProvisio gsepml format. LPM forward gsepml directly to
ningBatch... ]]> SEKMS without format validation.
</Sekms-data>

Note :
- Having both SecureElement and Sekms-data in
one command is not allowed.
- For batchfile and webservice xml, gsepml must
be wrapped by CDATA because LPM parser
does not know the format of gsepml.
- For the request with HProperties such as
CoreAPI and JMS Connector, CDATA is not
required.
APVM-specific (only work when all three parameters are presented.)

Key Derivation Profile Optional Key Derivation Profile for computing Card Security by
<CreateSubscription APVM
KeyDerivationProfile=""…

UICC Trigram Optional UICC Trigram for computing Card Security by APVM
<CreateSubscription
UICCTrigram=""…

MNO Trigram Optional MNO Trigram for computing Card Security by APVM
<CreateSubscription
MNOTrigram=""…

Example of command: creation of a card with a single key set.

<CreateSubscription
iccid="89492011110000009"
msisdn="0612131313"
imsi="00994911110000000"
initialState="ACTIVE"
cardProfile="GXX_v3.2_128K"
groupId="0612"
imei="359382005999999"
KeyDerivationProfile="KDP1"
UICCTrigram="GTO"
MNOTrigram="mno1">

<Ota-security>

5
6 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

<MBCard serialNumber="89492011110000009">
<SecurityDomain
securityDomainID="A000000018434D"
defaultSyncID="default"
implicitRcAlgoNumber="6"
proprietaryRcAlgoNumber="6" >
<Sync value="0000000000"/>
<Keyset versionNumber="2">
<Kic value="30423042304430443045304530463046" algoNumber="12"/>
<Kid value="0123456789ABCDEF100276FEDCBA0123" algoNumber="3"/>
</Keyset>
</SecurityDomain>
</MBCard>
</Ota-security>
</CreateSubscription>

Example : Full provisioning order creating a card in all the LinqUs products.

<CreateSubscription
iccid ="8997600370000000053"
imsi ="234500100000951"
msisdn ="33442360000"
initialState ="INACTIVE"
cardProfile ="03.20"
groupId="A+"
serviceExecutionProtocol="SMS"
imei="359382005999999">

<Ota-security>
<MBCard serialNumber="8997600370000000053">
<SecurityDomain
securityDomainID="A000000018434D08090A0B0C000000"
defaultSyncID="RFM"
implicitRcAlgoNumber="6"
proprietaryRcAlgoNumber="6">

<Sync value="0000000001"/>

<!-- Definition of key set for RFM -->


<Keyset versionNumber="1" syncID="SyncRFM">
<Sync value="0000000001"/>
<Kic value="D1F0…76E1" algoNumber="12"/>
<Kid value="A395…9DF6" algoNumber="3"/>
<!-- no Kik provided -->
</Keyset>

</SecurityDomain>
</MBCard>
</Ota-security>

<!-- Service Manager provisioning -->


<ServiceContent>
<Portal>
<Perso label="test" majorVersion="1" minorVersion="0"/>
</Portal>
</ServiceContent>

<!-- Subscriber Repository Manager provisioning -->


<SubscribeTo>
<Capabilities>
<Capability key="Prepaid" value="false"/>
<Capability key="Postpaid" value="true"/>
</Capabilities>
<SubscribedOptions>
<SubscribedOption name="NFC" state="ACTIVATED"/>
</SubscribedOptions>
</SubscribeTo>

<!-- Subscriber Repository Manager provisioning -->


<SubscribeTo>
<Capabilities>
<Capability key="Prepaid" value="false"/>
<Capability key="Postpaid" value="true"/>
</Capabilities>
<SubscribedOptions>

6
7

<SubscribedOption name="NFC" state="ACTIVATED"/>


</SubscribedOptions>
</SubscribeTo>

<!-- Device Manager provisioning -->


<Handset>
<Model manufacturer="LG" name="U300"/>
<SubscriptionList>
<Subscription
service="EMAIL"></Subscription>
</SubscriptionList>
<ServiceConfigurations>
<Service
type="EMAIL"
configured="true">
<GenericParameters name="email_vd2"></GenericParameters>
<UserDependentParameters>
<characteristic type="APPLICATION">
<characteristic type="APPADDR">
<characteristic type="PORT">
<parm name="PORTNBR" value="587"></parm>
</characteristic>
<parm name="ADDR" value="smtp.mail.yahoo.fr"></parm>
</characteristic>
<characteristic type="APPAUTH">
<parm name="AAUTHTYPE" value="None"></parm>
<parm name="AAUTHNAME" value="benoit"></parm>
<parm name="AAUTHSECRET" value="lpm"></parm>
</characteristic>
<parm name="TO-NAPID" value="NAP2"></parm>
<parm name="TO-NAPID" value="NAP1"></parm>
<parm name="PROVIDER-ID" value="PROVIDER1"></parm>
<parm name="NAME" value="ben_gemalto"></parm>
<parm name="RT-ADDR" value="ben_gemalto@yahoo.fr"></parm>
<parm name="FROM" value="ben_gemalto@yahoo.fr"></parm>
<parm name="TO-NAPID" value="NAP3"></parm>
<parm name="APPID" value="25"></parm>
</characteristic>
</UserDependentParameters>
</Service>
</ServiceConfigurations>
</Handset>

<ExecScript>
public class UpdateHPLMN2
{
public void script ()
{
// variables definitions
short MF = 0x3F00;
short DFGSM = 0x7F20;
short HPLMN = 0x6F31;

// Selection du fichier HPLMN


selectById(MF);
selectById(DFGSM);
selectById(HPLMN);

updateBinary((short)0, new byte[] {(byte)0x0B});


}
}
</ExecScript>
<SecureElement>
<DomainName>domain</DomainName>
<CACertificate>FF1122DD</CACertificate>
</SecureElement>
</CreateSubscription>

7
8 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Update Subscription
This command updates the subscription in any product present in the configuration.
The update of the subscription covers several cases:
1. Update the IMSI
2. Update the IMEI
3. Update the card’s state (DEACTIVATE or ACTIVATE)
4. Update the card’s group
5. Update the service portal.
All these cases can be mixed.
According to the different cases, the actions to take to update the products are different:

Parameter Type Description

currentICCID, currentIMSI and/or Conditional Accepts any of the three identifiers current MSISDN,
currentMSISDN current ICCID, and current IMSI. It is mandatory to
<UpdateSubscription provide one of the three. If several are provided, the
msisdnSrc="" ICCID is considered first, then the IMSI and MSISDN,
iccidSrc="" in that order.
imsiSrc=""…

IMSI Optional New IMSI. When new imsi is specified, the card must
<UpdateSubscription imsi=""… be identified with either msisdnScr or iccidSrc.
UpdateSubscription(ismsiScr, imsi) is not possible.

Initial State Optional Supported values: ACTIVE, INACTIVE or


<UpdateSubscription MARK_FOR_DELETION.
finalState=""… Default value is INACTIVE if MSISDN is not
specified, ACTIVE if MSISDN is specified.

Group Identifier Optional Relates to OTA Manager : identifier of the group that
<UpdateSubscription groupId=""… the card belongs to. This group must already be
defined.

Defining multiple group can be done by using pipe (|)


separator

For example:
groupId="group01|group04"

8
9

OTA security Optional Update Security domains (incl. OTA keys) and sync
counters
This parameter contains the complete security
<UpdateSubscription …> domain(s) that should be updated:
…  MBCard defines card security information
<Ota-security> (MBcardModule is invalid and should not be
<MBCard serialNumber="must defined in Ota-security).
contain iccid value">  List of synchronization counters (IDs and values)
…  For 03.48 cards, a list of security domains (ID,
</MBCard> default synchronization counter value, key sets,
</Ota-security> and so on)
…  For native cards, a list of security key files.
</UpdateSubscription >  The transportKey and algoName attribute must
be specified in the MBCard level or lower level
such as SecurityDomain, SecurityData or key
level.
Refer to the OTA Manager Provisioning Guide for
more details on security provisioning.
It may also contains sync counters that should be
updated (optional)

APVM-specific (only work when all three parameters are presented.)

Key Derivation Profile Optional Key Derivation Profile for computing Card Security by
<UpdateSubscription APVM
KeyDerivationProfile=""…

UICC Trigram Optional UICC Trigram for computing Card Security by APVM
<UpdateSubscription
UICCTrigram=""…

MNO Trigram Optional MNO Trigram for computing Card Security by APVM
<UpdateSubscription
MNOTrigram=""…

Device Manager-specific

IMEI Optional IMEI of the new subscriber’s handset.


<UpdateSubscription imei=""…

Handset.Groups.Group.name Optional LIST. Name of handset groups, for example


“PostPaid”.
Device Manager groups are different from OTA
Manager ones.
Service Manager-specific
<ServiceContent>
Optional
<Portal>
<Final label="test"
majorVersion="1"
minorVersion="0"/>
</Portal>
</ServiceContent>

ServiceContent.Portal.final.label Optional Label of portal to switch to. Defined only if different


<Final label="test" from the personalization portal. This call to Service
Manager 'Switch Portal' may generate SMS and
update the subscriber's card.

9
10 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

ServiceContent.Portal.final.major Conditional Major version of final portal. Defined only if a label is


Version specified. If no version is specified, SM chooses the
majorVersion="1" most recent portal (with the highest version).If only
major version is supplied, LPM sets minor version to
0.

ServiceContent.Portal.final.minor Conditional Minor version of final portal. Defined only if a label is


Version specified.
minorVersion="0"/>

ExecScript

Protocol Optional Specify the protocol that OTA Manager is to use for
<UpdateSubscription ExecScript execution. Valid choices are: CAT-TP or
serviceExecutionProtocol="SMS" SMS. If no value is specified, the default value is
taken from the OTA_PROTOCOL product parameter.

Script Optional Script to execute, specified as a string.


<ExecScript> Refer to the OTA Manager Script Programming
public class MyScript Guide for script syntax.
{...
}
</Execscript>

Subscriber Repository Manager-specific

Cause Optional Cause for card state variation.


<UpdateSubscription cause=""…
<SubscribeTo> Optional Capabilities and options for subscriptions.
<Capabilities>
<Capability key="Prepaid"
value="false"/>
</Capabilities>
<SubscribedOptions>
<SubscribedOption name="NFC"
state="ACTIVATED"/>
</SubscribedOptions>
</SubscribeTo>

SE-KMS-specific
Secure Element Optional Information of Secure Element to be updated in SE-
<SecureElement> KMS. It contains only CACertificate information. The
<DomainName>Domain_Name</Domai domain name and CACertificate are required.
nName>
<CACertificate>FF1122…</CACert
Update Subscription Command does not replace the
ificate> existing certificate. Instead, the CACertificate will be
</SecureElement> updated only by adding if it does not exist.

10
11

Sekms Data Optional Information of Secure Element to be created in


<Sekms-data> SEKMS. It contains provisioning data of SEKMS in
<![CDATA[<gsepml:ExecuteProvisio gsepml format. LPM forward gsepml directly to
ningBatch... ]]>
SEKMS without format validation.
</Sekms-data>

Note :
-Having both SecureElement and Sekms-data in
one command is not allowed.
-For batchfile and webservice xml, gsepml must
be wrapped by CDATA because LPM parser
does not know the format of gsepml.
- For the request with HProperties such as
CoreAPI and JMS Connector, CDATA is not
required.

Example of command: setting the IMEI, changing the state of a subscriber.


<!—- IMEI Change -->
<UpdateSubscription msisdnSrc="9911111111" imei="359382005999999"/>

<!—- State Change -->


<UpdateSubscription msisdnSrc="9911111112" finalState="INACTIVE"/>

<!—- State Change -->


<UpdateSubscription iccidSrc="8997600370000000053" finalState="ACTIVE"/>

<!—- Security Change -->


<UpdateSubscription
msisdnSrc ="33650000000">

<Ota-security>
<MBCard serialNumber="89492033650000000">
<SecurityDomain securityDomainID="A000000018434D08090A0B0C000000" defaultSyncID="default"
implicitRcAlgoNumber="6" proprietaryRcAlgoNumber="6">
<Sync value="0000000000"/>
<Keyset versionNumber="1" syncID="Domain1KeySet1">
<Sync value="0000000001"/>
<Kic value="000102030405060708090A0B0C0D0E0F" algoNumber="12"/>
<Kid value="000102030405060708090A0B0C0D0E0F" algoNumber="3"/>
</Keyset>
<Keyset versionNumber="2" syncID="Domain1KeySet2" >
<Sync value="0000000001"/>
<Kic value="000102030405060708090A0B0C0D0E0F" algoNumber="12"/>
<Kid value="000102030405060708090A0B0C0D0E0F" algoNumber="3"/>
</Keyset>
</SecurityDomain>
</MBCard>
</Ota-security>

<!—- Switch Portal -->


<UpdateSubscription msisdnSrc="9911111112">
<ServiceContent>
<Portal>
<Final label="Post-Paid" majorVersion="1" minorVersion="0" />
</Portal>
</ServiceContent>
</UpdateSubscription>

<!—- Subscriber Repository -->


<UpdateSubscription msisdnSrc="9911111112" finalState="ACTIVE" cause="Card activated">
<SubscribeTo>
<Capabilities>
<Capability key="Prepaid" value="false"/>
<Capability key="Postpaid" value="true"/>
</Capabilities>
<SubscribedOptions>

11
12 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

<SubscribedOption name="NFC" state="ACTIVATED"/>


</SubscribedOptions>
</SubscribeTo>
</UpdateSubscription>

<!—- Secure Element -->


<UpdateSubscription msisdnSrc="9911111112">
<SecureElement>
<DomainName>domain</DomainName>
<CACertificate>FF1122DD</CACertificate>
</SecureElement>
</UpdateSubscription>

12
13

Change MSISDN
This command allows you to change the MSISDN of an existing SIM card.

Parameter Type Description

ICCID, IMSI and/or MSISDN Conditional At least one ICCID or IMSI identifier is required. If
<ChangeMSISDN more than one identifier is specified, priority is:
iccid="" ICCID then IMSI, then MSISDN. Note: The Change
imsi=""… MSISDN command cannot be replayed unless the
msisdnSrc="" MSISDN parameter is provided, even if it is empty.
ChangeMSISDN(msisdnScr,msisdn) is not
possible.

MSISDN Mandatory New MSISDN


<ChangeMSISDN msisdn=""

State Mandatory Final state of the card: ACTIVE, INACTIVE or


<ChangeMSISDN finalState=""… MARK_FOR_DELETION

ExecScript

Protocol Optional Specify the protocol that OTA Manager is to use for
<ChangeMSISDN the ExecScript execution. Valid choices are:
serviceExecutionProtocol="SMS" CAT-TP or SMS. If no value is specified, the default
value is taken from the OTA_PROTOCOL product
parameter.

Script Optional Script to execute, specified as a string.


<ExecScript> Refer the OTA Manager Script Programming Guide
public class MyScript for script syntax.
{...
}
</Execscript>

Subscriber Repository Manager-specific

Cause Optional Cause for card state variation.


< ChangeMSISDN cause=""…

Example of command:

<ChangeMSISDN
iccid="89492011110000009"
msisdn="0612131313"
finalState="ACTIVE"
cause=="Card activated"
/>

13
14 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Smart Change MSISDN


This command allows you to change the MSISDN of an existing SIM card. However, it is different from the
standard Change MSISDN command since, in case the msisdn is already used by another SIM card, it first
deactivates this other card before performing the msisdn change on the target SIM card.

Parameter Type Description

ICCID Conditional The identifier of the subscription’s card on which


<SmartChangeMSISDN the change msisdn should be performed.
iccid="" Caution: If both iccid and imsi are specified, the
subscription will be retrieved using iccid.

IMSI Conditional The current IMSI of the subscription on which the


<SmartChangeMSISDN change msisdn should be performed.
imsi=”” Caution: If both iccid and imsi are specified, the
subscription will be retrieved using iccid

MSISDN SRC Optional The current MSISDN of the subscription on which


<SmartChangeMSISDN the change msisdn should be performed.
msisdnSrc=””
Caution: This parameter is not used to retrieve the
target subscription: when specified (optional), it is
used to check that the target subscription is
consistent:
(subscription.msisdn=msisdnSrc)

CARD PROFILE Optional The card profile of the target subscription on which
<SmartChangeMSISDN the change msisdn should be performed.
cardProfile=”” Caution: when specified (optional), it is only used
to check that the target subscription is consistent:
(subscription.cardProfile=cardProfile)

MSISDN Mandatory The final msisdn to set on the target subscription.


<SmartChangeMSISDN msisdn=""

State Mandatory The final state of the subscription after the change.
<SmartChangeMSISDN Possible values are ‘ACTIVE’ or ‘INACTIVE’ or
finalState=""… ‘MARK_FOR_DELETION’.

ExecScript

Protocol Optional In case an execution script is specified, this


<SmartChangeMSISDN parameter defines the protocol used to perform the
serviceExecutionProtocol="SMS" over the air script execution. Possible values are
SMS or CAT-TP.
If not set, the protocol will be the one configured for
the LPM instance. If protocol is not configured for
LPM instance, protocol finally used will be SMS.

Script Optional Script to execute, specified as a string.


<ExecScript> Refer the OTA Manager Script Programming Guide
public class MyScript for script syntax.
{...
}
</Execscript>

14
15

Subscriber Repository Manager-specific

Cause Optional Cause for card state variation.


<SmartChangeMSISDN cause=""…

Example of command:

<SmartChangeMSISDN
iccid="89492011110000009"
msisdn="0612131313"
finalState="ACTIVE"
cause=="Card activated"
/>

15
16 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Change SIM card


This command allows an MSISDN to be transferred from an initial card to a source card. The initial card is
flagged as "Mark for deletion".

Parameter Type Description

ICCID, IMSI and/or MSISDN Conditional Identifier of the current card. This
<ChangeSIM command accepts any of the three
iccidSrc="" identifiers MSISDN, ICCID, and IMSI. It is
imsiSrc="" mandatory to provide one of the three. If
msisdn=""…
more than one are provided, the
command first checks that the provided
values are consistent with the one set in
each product.

ICCID, IMSI Conditional New identifier of the card. One of the


<ChangeSIM identifiers must be specified.
iccid=""
imsi=""…

Group Identifier Optional Add the destination card to one or more


<ChangeSIM groupId=""… groups. If not defined, the group in
destination card and source card will be
the same.

Defining multiple group can be done by


using pipe (|) separator

For example:
groupId="group01|group04"

Card Profile Optional Name of the new card profile to assign to


<ChangeSIM cardProfile="" the card.

State Mandatory Final state of the card: ACTIVE,


<ChangeSIM finalState=""… INACTIVE or MARK_FOR_DELETION

Protocol Optional Specify the protocol that OTA Manager is


<ChangeSIM serviceExecutionProtocol="SMS" to use for the ExecScript execution. Valid
choices are: CAT-TP or SMS. If no value
is specified, the default value is taken
from the OTA_PROTOCOL product's
parameter.

Script Optional Script to execute, specified as a string,


<ExecScript> Refer to the OTA Manager Script
public class MyScript Programming Guide for script syntax.
{...
}
</Execscript>

Subscriber Repository Manager-specific

Cause Optional Cause for card state variation.


< ChangeSIM cause=""…

16
17

SE-KMS-specific

Secure Element Optional Information of Secure Element to be


<SecureElement> updated in SE-KMS. It contains only
<DomainName>Domain_Name</DomainName> CACertificate information. The domain
<CACertificate>FF1122…</CACertificate> name and CACertificate are required.
</SecureElement> Change SIM Command does not replace
the existing certificate. Instead, the
CACertificate will be updated only by
adding if it does not exist.
Sekms Data Optional Information of Secure Element to be
<Sekms-data> created in SEKMS. It contains provisioning
<![CDATA[<gsepml:ExecuteProvisioningBatch... data of SEKMS in gsepml format. LPM
]]> forward gsepml directly to SEKMS without
</Sekms-data> format validation.

Note :
-Having both SecureElement and
Sekms-data in one command is
not allowed.
-For batchfile and webservice xml,
gsepml must be wrapped by
CDATA because LPM parser does
not know the format of gsepml.
- For the request with HProperties
such as CoreAPI and JMS
Connector, CDATA is not required.

<ChangeSIM iccidSrc="8941010000000000011" iccid="8941010000000000031" finalState="ACTIVE"/>

<ChangeSIM
iccidSrc="89492011110000000"
imsiSrc="00894911110000000"
msisdn= "1234"
iccid="99492011110000000"
imsi="00994911110000000"
finalState= "ACTIVE"
cause= "Changed by user"
groupId= "postpaid"
cardProfile="test" />

<ChangeSIM
iccidSrc="89492011110000000"
imsiSrc="00894911110000000"
msisdn= "1234"
iccid="99492011110000000"
imsi="00994911110000000"
finalState= "ACTIVE"
groupId= "postpaid"
cardProfile="test" >

<SecureElement>
<DomainName>domain</DomainName>
<CACertificate>FF1122DD</CACertificate>
</SecureElement>
</ChangeSIM>

17
18 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Delete Subscription
This command deletes the subscription from any product present in the configuration.
In certain conditions, the Update Subscription command can be used to inactivate the card from the product
without deleting it: set the state to INACTIVE.

Parameter Type Description

ICCID, IMSI and/or MSISDN Conditional Identifier of the subscription to delete. This
<DeleteSubscription command accepts any of the three identifiers
iccid="" MSISDN, ICCID, and IMSI. It is mandatory to
imsi="" provide one of the three. If more than one are
msisdn=""…
provided, the command first checks that the
provided values are consistent with the one
set in the OTA. Otherwise, the command is
rejected with error code PM-204.

DELETE_SECURITY Optional Accepted values are TRUE or FALSE.


<DeleteSubscription Default behaviour if missing or incorrect value
deleteSecurity="true" is TRUE
Note :
If 'deleteSecurity' field is set to 'false', the
corresponding security bundle in OTA and
Sekms-data will not be deleted even though
the <SecureElement> is defined in command.
If 'deleteSecurity' field is set to 'true', the
corresponding security bundle in OTA, and all
Sekms data including CACertificate in
SEKMS will be deleted.

SE-KMS-specific

Secure Element Optional This parameter is not mandatory for deleting


<SecureElement> Sekms-data. If the Domain Name is present,
<DomainName>Domain_Name</DomainName> SEKMS will ensure that UICC is associated
</SecureElement> to the specified Domain Name.
Note :
Secure Element Parameter is deprecated
since LPM 5.2.6 or later and SEKMS-1.4.1.0
or later

<DeleteSubscription iccid="8941010000000000013" deleteSecurity="true"/>

<DeleteSubscription iccid="8941010000000000013" deleteSecurity="true">


<SecureElement>
<DomainName>domain</DomainName>
</SecureElement>
</DeleteSubscription>

18
19

Get Subscription Information


This command allows you to obtain the current subscription status in the whole set of installed product
(ignores the product for which the corresponding connector is deactivated or not installed).
This command can be used through a SOAP request or using the Customer Care Interface.
Batch API does not support getSubscriptionInformation command.

Parameter Type Description

ICCID, IMSI or MSISDN Mandatory Identifier of the subscription to read. This command
<GetSubscriptionInformation accepts any of the three identifiers MSISDN, ICCID,
iccid="" and IMSI. It is mandatory to provide one of the three
imsi="" and only one. The command first checks that there is
msisdn=""…
only one identifier. Otherwise, the command is
rejected with error code PM-13

<GetSubscriptionInformation iccid="8941010000000000013"/>

19
20 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Get Subscription Information Response


This paragraph describes the format of GetSubscriptionInformation command response.
Subscription's data are presented in separate elements, reflecting targeted products (<ota>, <dm>…). The
response may contain two elements of the same type (for example, Phone Book data are split into two
elements of the type <pb>).
These elements are not sorted.
The presence (or absence) of the subscription in a product is specified into the field "subscription_status"
("present", "missing"). If the dedicated service connector is not active, or if the key to read subscription
information into the product database is not known (for example, the MSISDN for Device Manager) the
"subscription_status" will be "unknown".
Other data are returned only if the subscription is present.

For any particular information about subscription's specific product's data, please refer to concerned
product's documentation.

Parameter Description
<GetSubscriptionInformation
The targeted id of the card (iccid/imsi or msisdn)
iccid=""
imsi=""
The targeted imsi if set
msisdn =""
The targeted msisdn if set

OTA Manager-specific

OTA card OTA card is get by input target (ICCID, IMSI or


<ota MSISDN)
imsi="" subscription_status=present, missing, unknown
msisdn=""
card_state =0,1,2 (Inactive/Active/ Mark for deletion)
profile_name=""
card_state="1" applets.applet.state =1,2,3,4 (Installed/
subscription_status="present" Selectable/Locked/Personalized)
iccid="">
<applets>
<applet
sd=""
label=""
aid=""
state="2"></applet>
</applets>
</ota>

OTA security
No information on card security is get by the
command
GetSubscriptionInformation
Device Manager-specific

20
21

<dm DM subscription is get by MSISDN


imsi=""
msisdn=""
subscription_status=present, missing, unknown
manufacturer="" handset_state=0,1 (inactive,active)
handset_state="1"
model=""
subscription_status="present"></dm>

Device Detection Manager-specific


<ddm DDM subscription is get by IMSI, MSISDN, ICCID
imei="" (priority order)
subscription_status="present"></ddm>
subscription_status=present, missing, unknown
Service Manager-specific
<sm SM subscription is get by MSISDN or ICCID (priority
service_content_status="Not locked" order)
msisdn=""
subscription_status=present, missing, unknown
portal_name=""
service_profile_name="" service_content_status=Not locked, Unknown
subscription_status="present" simcard_status=Not locked, Unknown
simcard_status="Not locked"
iccid=""></sm>

PhoneBook-specific
<pb PB subscription is get by MSISDN or ICCID (priority
subscription_status="present" order)
mapping_user_id=""
subscription_status=present, missing, unknown
mapping_simcard_id=""
mapping_mobile_id="" mapping_user_id=msisdn
mapping_status="partial" mapping_simcard_id=iccid
mapping_state="1" mapping_mobile_id=imei
mapping_id=""
mapping_status=partial, complete
mapping_syncml_id="gemplus.sim.native"
mapping_simcard_profile_name=""></pb> mapping_state=1, 0, 2 (Active/Inactive/ Mark for
deletion)
mapping_id=msisdn
Subscriber Repository Manager-specific
<srm SRM subscription is get by MSISDN or ICCID
subscription_status="present" (priority order)
iccid=""
subscription_status=present, missing, unknown
msisdn=""
imsi="" mapping_status=0,1,2,3
imei="" (created/activated/suspended/canceled)
mapping_status=""
<capabilities> All fields are mandatory except capabilities and
<capability options.
capability_name=""
value=""></capability>

</capabilities>
<options>
<option
option_name=""
state=""></option>

</options>
=""></srm>

21
22 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Examples :

<GetSubscriptionInformation
iccid="89492033603000011">
<pb
subscription_status="present"></pb>
<ota
imsi="00894933603000011"
msisdn="33603000011"
profile_name="GXX_v3.2_128K"
card_state="1"
subscription_status="present"
iccid="89492033603000011">
<applets>
<applet
sd="A000000018434D08090A0B0C000000"
label="RAM applet instance"
aid="A000000018434D08090A0B0C000000"
state="2"></applet>
<applet
sd="A000000018434D08090A0B0C000000"
label="RFM applet instance"
aid="A00000001803090000000000B00010"
state="2"></applet>
</applets>
</ota>
<dm
imsi="00894933603000011"
msisdn="33603000011"
manufacturer="LG"
handset_state="1"
model="U300"
subscription_status="present"></dm>
<ddm
imei="3579720003000011"
subscription_status="present"></ddm>
<sm
service_content_status="Not locked"
msisdn="33603000011"
portal_name="empty"
service_profile_name="empty"
subscription_status="present"
simcard_status="Not locked"
iccid="89492033603000011"></sm>
<pb
mapping_user_id=""
mapping_simcard_id="89492033603000011"
mapping_mobile_id="3579720003000011"
mapping_status="partial"
mapping_state="1"
mapping_id="33603000011"
mapping_syncml_id="gemplus.sim.native"
mapping_simcard_profile_name="PROFILE_TEST"></pb>
</GetSubscriptionInformation>

Example of getSubscriptionInformation response: some connector are deactivated

<GetSubscriptionInformation
iccid="8949203360300011">
<ddm
subscription_status="unknown"></ddm>

22
23

<dm
subscription_status="unknown"></dm>
<pb
subscription_status="unknown"></pb>
<ota
imsi="0089493360300011"
msisdn="3360300011"
profile_name="GXX_v3.2_128K"
card_state="0"
subscription_status="present"
iccid="8949203360300011">
<applets>
<applet
sd="A000000018434D08090A0B0C000000"
label="RAM applet instance"
aid="A000000018434D08090A0B0C000000"
state="2"></applet>
<applet
sd="A000000018434D08090A0B0C000000"
label="RFM applet instance"
aid="A00000001803090000000000B00010"
state="2"></applet>
</applets>
</ota>
<sm
service_content_status="Not locked"
msisdn="3360300011"
portal_name="empty"
service_profile_name="empty"
subscription_status="present"
simcard_status="Not locked"
iccid="8949203360300011"></sm>
<srm
subscription_status="present"
imsi="00894933603000011"
msisdn="33603000011"
iccid="00894933603000011"
imei="00894933603000011"
mapping_status="1"></srm>

</GetSubscriptionInformation>

Example of getSubscriptionInformation response: the subscription does not exist

<GetSubscriptionInformation
iccid="0000000000000">
<ota
subscription_status="missing"></ota>
<sm
subscription_status="missing"></sm>
<ddm
subscription_status="missing"></ddm>
<dm
subscription_status="unknown"></dm>
<pb
subscription_status="missing"></pb>
<srm
subscription_status="missing"></srm>

</GetSubscriptionInformation>

23
24 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Create Subscription 4AP


This command creates a subscription for auto provisioning in any available product present in the
configuration, with specified input parameters. The OTA Manager product must be installed.

Parameters
The command accepts the following parameters:

Parameter Type Description

ICCID Mandatory The ICCID of a new SIM card.


<CreateSubscription4AP iccid=""

IMSI Mandatory The IMSI of a new SIM card.


<CreateSubscription4AP imsi=""… in classic
provisioning

Optional in
NG
provisioning
with SPS

MSISDN Optional The phone number of the new subscription, usually


<CreateSubscription4AP msisdn not known at the personalization stage.
=""…
Mandatory if the initial State is ACTIVE

Initial State Mandatory ACTIVE, INACTIVE


<CreateSubscription4AP
initialState=""…

OTA Manager-specific

Card Profile Mandatory Associate the card with an electrical profile (a set of
<CreateSubscription4AP files and applets loaded during the personalization
cardProfile=""…
stage).

Group identifiers Optional Add the card to one or more groups.


<CreateSubscription4AP
groupId=""…
Defining multiple group can be done by using pipe (|)
separator

For example:
groupId="group01|group04"

24
25

OTA security Optional Create Security domains and OTA keys.


Providing OTA security is not mandatory in the
Create Subscription command, but it is generally
<CreateSubscription4AP …> mandatory to update the card after issuance.
… This parameter contains the complete security
<Ota-security> definition for the card:
<MBCard serialNumber="must
contain iccid value">
 MBCard defines card security information

(MBcardModule is invalid and should not be
defined in Ota-security).
</MBCard>
 List of synchronization counters (IDs and values)
</Ota-security>
 For 03.48 cards, a list of security domains (ID,

default synchronization counter value, key sets,
</CreateSubscription4AP >
and so on)
 For native cards, a list of security key files.
 The transportKey and algoName attribute must
be specified in the MBCard level or lower level
such as SecurityDomain, SecurityData or key
level.
Refer to the OTA Manager Provisioning Guide for
more details on security provisioning.

Service Manager-specific
<ServiceContent> Optional
<Portal>
<Perso label="test"
majorVersion="1"
minorVersion="0"/>
</Portal>
</ServiceContent>

ServiceContent.Portal.perso.label Optional Label of portal defined during the card


<Perso label="test"… personalization phase. The Perso portal must be
declared in the Service structure of the Service
Manager and linked to the OTA card profile

Conditional Major version of personalization portal. Can be


ServiceContent.Portal.perso.major
Version defined only if a label is specified. If no version is
specified, SM chooses the most recent portal (with
majorVersion="1"
the highest version).If only major version is supplied,
LPM sets minor version to 0.
ServiceContent.Portal.perso. Conditional Minor version of personalization portal. Can be
minorVersion defined only if a label is specified.
minorVersion="0"/>

ExecScript
ServiceCallProtocol Optional Whether to use the SMS or CAT-TP (BIP) protocol
<CreateSubscription4AP when calling services. If no value is specified, the
serviceExecutionProtocol="SMS" default value is taken from the OTA_PROTOCOL
product parameter.

25
26 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Script Optional The script to execute, specified as a string.


<ExecScript>
public class MyScript
Refer to the OTA Manager Script Programming
{...
Guide for script syntax.
}
</Execscript>

Subscriber Repository Manager-specific


<SubscribeTo> Optional Capabilities and options for subscriptions.
<Capabilities>
<Capability key="Prepaid"
value="false"/>
</Capabilities>
<SubscribedOptions>
<SubscribedOption name="NFC"
state="ACTIVATED"/>
</SubscribedOptions>
</SubscribeTo>

SE-KMS-specific
Secure Element Optional Information of Secure Element to be created in SE-
<SecureElement> KMS. It contains only CACertificate information. The
<DomainName>Domain_Name</Domai domain name and CACertificate are required.
nName>
<CACertificate>FF1122…</CACert
ificate>
</SecureElement>

Sekms Data Optional Information of Secure Element to be created in


<Sekms-data> SEKMS. It contains provisioning data of SEKMS in
<![CDATA[<gsepml:ExecuteProvisio gsepml format. LPM forward gsepml directly to
ningBatch... ]]> SEKMS without format validation.
</Sekms-data>

Note :
- Having both SecureElement and Sekms-data in
one command is not allowed.
- For batchfile and webservice xml, gsepml must
be wrapped by CDATA because LPM parser
does not know the format of gsepml.
- For the request with HProperties such as
CoreAPI and JMS Connector, CDATA is not
required.

Example of command: creation of a card with a single key set.

<CreateSubscription4AP
iccid="89492011110000009"
msisdn="0612131313"
imsi="00994911110000000"
initialState="ACTIVE"
cardProfile="GXX_v3.2_128K"
groupId="0612"
imei="359382005999999">

<Ota-security>
<MBCard serialNumber="89492011110000009">
<SecurityDomain
securityDomainID="A000000018434D"
defaultSyncID="default"
implicitRcAlgoNumber="6"
proprietaryRcAlgoNumber="6" >
<Sync value="0000000000"/>
<Keyset versionNumber="2">

26
27

<Kic value="30423042304430443045304530463046" algoNumber="12"/>


<Kid value="0123456789ABCDEF100276FEDCBA0123" algoNumber="3"/>
</Keyset>
</SecurityDomain>
</MBCard>
</Ota-security>
</CreateSubscription4AP>

Example : Full provisioning order creating a card in all the LinqUs products.

<CreateSubscription4AP
iccid ="8997600370000000053"
imsi ="234500100000951"
msisdn ="33442360000"
initialState ="INACTIVE"
cardProfile ="03.20"
groupId="A+"
serviceExecutionProtocol="SMS"
imei="359382005999999">

<Ota-security>
<MBCard serialNumber="8997600370000000053">
<SecurityDomain
securityDomainID="A000000018434D08090A0B0C000000"
defaultSyncID="RFM"
implicitRcAlgoNumber="6"
proprietaryRcAlgoNumber="6">

<Sync value="0000000001"/>

<!-- Definition of key set for RFM -->


<Keyset versionNumber="1" syncID="SyncRFM">
<Sync value="0000000001"/>
<Kic value="D1F0…76E1" algoNumber="12"/>
<Kid value="A395…9DF6" algoNumber="3"/>
<!-- no Kik provided -->
</Keyset>

</SecurityDomain>
</MBCard>
</Ota-security>

<!-- Service Manager provisioning -->


<ServiceContent>
<Portal>
<Perso label="test" majorVersion="1" minorVersion="0"/>
</Portal>
</ServiceContent>

<!-- Subscriber Repository Manager provisioning -->


<SubscribeTo>
<Capabilities>
<Capability key="Prepaid" value="false"/>
<Capability key="Postpaid" value="true"/>
</Capabilities>
<SubscribedOptions>
<SubscribedOption name="NFC" state="ACTIVATED"/>
</SubscribedOptions>
</SubscribeTo>

<!-- Subscriber Repository Manager provisioning -->


<SubscribeTo>
<Capabilities>
<Capability key="Prepaid" value="false"/>
<Capability key="Postpaid" value="true"/>
</Capabilities>
<SubscribedOptions>
<SubscribedOption name="NFC" state="ACTIVATED"/>
</SubscribedOptions>
</SubscribeTo>

27
28 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

<ExecScript>
public class UpdateHPLMN2
{
public void script ()
{
// variables definitions
short MF = 0x3F00;
short DFGSM = 0x7F20;
short HPLMN = 0x6F31;

// Selection du fichier HPLMN


selectById(MF);
selectById(DFGSM);
selectById(HPLMN);

updateBinary((short)0, new byte[] {(byte)0x0B});


}
}
</ExecScript>
<SecureElement>
<DomainName>domain</DomainName>
<CACertificate>FF1122DD</CACertificate>
</SecureElement>
</CreateSubscription4AP>

28
29

2
The SOAP API

Architecture and Description

SOAP client

Provisioning commands:
SOAP messages Internet / Intranet
XML/http

SOAP server - Tomcat 5


LPM Web services: LogonManager,
ProvisioningManager

pm.properties file

WS input connector

LinqUs
Provisioning Manager

The SOAP client invokes the LinqUs Provisioning Manager SOAP API using the following URLs:
http://[hostname]:[port]/PM/services/LogonManager
or
http://[hostname]:[port]/PM/services/ProvisioningManager
Where:

[hostname] The name of the machine hosting the SOAP server

[port] The SOAP Web server port

PM The application name in the SOAP Web server (usually the same as
your LinqUs Provisioning Manager product instance name).

29
30 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

LogonManager Service to log in to and log out from the platform.

ProvisioningManager Service to invoke all standard and custom LinqUs Provisioning Manager
commands, in either synchronous mode (waiting for the response) or
asynchronous mode (no waiting), and to get a command report or a list
of command reports(asynchronous usage).
LinqUs Provisioning Manager Web services operations require the following identification information:

token Contains the user rights to access the platform. This token is calculated at logon
time, and must be provided for any provisioning operation

filename The name of a properties file that contains the targeted platform and LinqUs
Provisioning Manager product instance.

SOAP API Request Life Cycle

Web Services Client LinqUs Provisioning Manager


Web Services
Client LogonManager ProvisioningManager

logon (user, password)

token

executeAsynchronousCommand (token + command)

ID (invocation)

getReport (InvocationId)

endingStatus

logout

LPM SOAP Operations syntax


Colors' keys used in the examples that follow:
<pm:token> Logon token information
<pm:filename> LPM configuration file information
<pm:command> Request and command information
<pm:logon> SOAP service or operation information

30
31

Login/logout Operations – Token Usage

The LinqUs Provisioning Manager LogonManager Web service provides an operation named logon, which
obtains an identification token from the LinqUs platform.
This token has to be provided to any operation of LinqUs Provisioning Manager ProvisioningManager
Web service. It is transmitted to the platform to control access rights.
This token is given for the user provided to logon operation.
An authentication control (user/password) is done at token calculation time.

Token Characteristics
The validity period of the token is based on the “Maximum access duration” time, read from the user's
profile.
The user provided to the logon operation must have sufficient rights to perform the provisioning operations
that will be performed on the products (createSubscription, getSubscriptionInformation, getReport, and
so on).
The user profile rights and validity period are checked for each request issued to the platform.

Example of Token Usage


The following request:


<pm:logon>
<pm:filename>pm</pm:filename>
<pm:user>soapuser</pm:user> <!-- to get a token from LinqUs platform -->
<pm:password>soapuser_pwd</pm:password>
</pm:logon>

returns a token value for the user soapuser in <logonReturn>:


<logonResponse xmlns="http://soap.pm.gemalto.com">
<logonReturn>
rO0ABXctEQAKYWRtZ2VtYWx0bxEADUFkbWluaXN0cmF0b3IAAAAAAAAAAAAAAAAAAAAA
</logonReturn>
</logonResponse>

This token has to be passed to other operations:


<pm:executeSynchronousCommand>
<pm:filename>pm</pm:filename>
<pm:token>
rO0ABXctEQAKYWRtZ2VtYWx0bxEADUFkbWluaXN0cmF0b3IAAAAAAAAAAAAAAAAAAAAA
</pm:token>
<pm:command>
<![CDATA[
<Order>
<... My LPM or CUSTOM command here .../>
</Order>
]]>
</pm:command>
</pm:executeSynchronousCommand>


<pm:logout>
<pm:filename>pm</pm:filename>

31
32 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

<pm:token>
rO0ABXctEQAKYWRtZ2VtYWx0bxEADUFkbWluaXN0cmF0b3IAAAAAAAAAAAAAAAAAAAAA
</pm:token>
</pm:logout >

Note: The logout operation is not implemented yet.

Properties File Usage – Filename


Any operation request issued to the LinqUs Provisioning Manager Web services (LogonManager or
ProvisioningManager) needs to first request a connection:
 To the LinqUs platform, and
 To the appropriate LinqUs Provisioning Manager product instance and Web services input connector.
The connection request to LPM product instance, creates an authentication control depending on the
properties pm.connection.username and pm.connnection.password found in the properties file. The
name of this file must be provided to any operation issued to the LinqUs Provisioning Manager Web
services.
The user specified in the properties file to get the connection to the LPM product instance must have
sufficient rights to perform the provisioning operations on each individual LinqUs product (OTA Manager,
DM, and so on).

Example of Properties File Use

The following request:


<pm:logon>
<pm:filename>pm</pm:filename> <!-- for "pm.properties"-->
<pm:user>soapuser</pm:user>
<pm:password>soapuser_pwd</pm:password>
</pm:logon>

connects to the LinqUs platform using the pm.connection.username and pm.connection.password


property values, defined in the file pm.properties, and then connects to the LinqUs Provisioning Manager
instance targeted by the property pm.product.name.

Note: The properties file is created when the LinqUs Provisioning Manager Web services are installed. It is
located in the SOAP Web server tree and contains mandatory information to connect to the platform:
LinqUs Provisioning Manager instance name, Visibroker properties (agent port and address), Web services
connector name, and so on. See LinqUs Provisioning Manager Administration guide for mode information
on pm.properties file.

Caution: The file name must be specified without an extension ("pm" for "pm.properties").

Provisioning Operations
The LinqUs Provisioning Manager ProvisioningManager Web service provides the following operations:
 executeSynchronousCommand. Executes a provisioning command in synchronous mode. The
execution of the operation waits for the result. The command result is provided in the operation
response.
 executeAsynchronousCommand. Executes a provisioning command in asynchronous mode and
returns an invocation identifier. This invocation identifier is used by the getReport operation to retrieve
the result of the execution of the command.
 getReport. Retrieves the result of a previously executed provisioning command.

32
33

 getReports. Retrieves the results of multiple previously executed provioning commands.


A LinqUs Provisioning Manager provisioning command (any standard or custom provisioning command) is
passed to the Web service operation in XML format embedded in a CDATA section. This XML command
must be valid according to the LinqUs Provisioning Manager commands schema.
The format is described in Chapter 2.
An XML format LinqUs Provisioning Manager command requested to Web services is equivalent to an XML
command embedded in a LinqUs Provisioning Manager batch file.

Asynchronous Command Example


<pm:executeAsynchronousCommand>
<pm:filename>... my properties file name here .../pm:filename>
<pm:token>... my token here ...</pm:token>
<pm:command>
<![CDATA[
<Order>
<DeleteSubscription iccid="89492033603000015"/> <!-- LPM commands syntax -->
</Order>
]]>
</pm:command>
</pm:executeAsynchronousCommand>

Returns the following Invocation ID:


<executeAsynchronousCommandResponse xmlns="http://pm.soap.pm.gemalto.com">
<executeAsynchronousCommandReturn>
<ID>496950</ID> <!-- invocation ID -->
<endUser>soapuser</endUser>
<endingExecutionDate>0</endingExecutionDate>
<endingStatus>0</endingStatus>
<endingStatusLabel>NOT_AVAILABLE</endingStatusLabel>
<expirationDate>1206721977291</expirationDate>
<invoker>wsConnector1</invoker>
<processingDate>0</processingDate>
<resultData xsi:nil="true"/>
<serviceName>DeleteSubscription</serviceName>
<state>1</state>
<stateLabel>SUBMITTED</stateLabel>
<submissionDate>1206721077291</submissionDate>
<transactionID/>
</executeAsynchronousCommandReturn>
</executeAsynchronousCommandResponse>

This invocation ID is used to obtain the command’s result:


<pm:getReport>
<pm:filename>... my properties file name here .../pm:filename>
<pm:token>... my token here ...</pm:token>
<pm:invocationId>496950<pm:invocationId>
</pm:getReport>

This in turn returns the command’s end status and error codes:


<getReportResponse xmlns="http://pm.soap.pm.gemalto.com">
<getReportReturn>
<ID>496950</ID>
<endUser>soapuser</endUser>
<endingExecutionDate>1206721077448</endingExecutionDate>

33
34 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel> <!-- ending status -->
<expirationDate>1206721977291</expirationDate>
<invoker>wsConnector1</invoker>
<processingDate>0</processingDate>
<resultData>
<Order enduser="soapuser">
<DeleteSubscription iccid"89492033603000015">
</DeleteSubscription>
</Order>
</resultData>
<serviceName>CreateSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1206721077291</submissionDate>
<transactionID xsi:nil="true"/>
</getReportReturn>
</getReportResponse>

The sample SOAP request to get multiple reports:


<getReports xmlns="http://pm.soap.pm.gemalto.com">
<filename>pm</filename>
<token>rO0ABXdCAAABJvau9B8RAAphZG1nZW1hbHRvEQANQWRtaW5pc3RyYXRvcgAAAAAAAAAAAAAAAAAAA
AACAAAAAAAAASb2rqrBdAAMRXVyb3BlL1Bhcmlzdw4AAAADAQAAAAASAAAAFHcUx8wygHyVXwGP5MiGS8ZlpvnvGmM=</tok
en>
<invocationIds>271062</invocationIds>
<invocationIds>271063</invocationIds>
<invocationIds>271064</invocationIds>
</getReports>

And the result is a list of invocations:

<getReportsResponse xmlns="http://pm.soap.pm.gemalto.com">
<getReportsReturn>
<ID>271062</ID>
<endUser>admgemalto</endUser>
<endingExecutionDate>1266859057316</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1266859946439</expirationDate>
<invoker>ws_auto</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order transactionId=”Test Unit” enduser=”admgemalto”>
<DeleteSubscription iccid=”12345123451234”></DeleteSubscription></Order>
]]>
</resultData>
<serviceName>DeleteSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1266859046439</submissionDate>
<transactionID>Test JUnit</transactionID>
</getReportsReturn>
<getReportsReturn>
<ID>271063</ID>
<endUser>admgemalto</endUser>
<endingExecutionDate>1266859059673</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1266859957610</expirationDate>
<invoker>ws_auto</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order transactionId=”Test Unit” enduser=”admgemalto”>
<DeleteSubscription iccid=”12345123451236”></DeleteSubscription></Order>
]]>

34
35

</resultData>
<serviceName>DeleteSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1266859057610</submissionDate>
<transactionID>Test JUnit 2</transactionID>
</getReportsReturn>
<getReportsReturn>
<ID>271064</ID>
<endUser>admgemalto</endUser>
<endingExecutionDate>1266859062695</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1266859959802</expirationDate>
<invoker>ws_auto</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order transactionId=”Test Unit” enduser=”admgemalto”>
<DeleteSubscription iccid=”12345123451237”></DeleteSubscription></Order>
]]>

</resultData>
<serviceName>DeleteSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1266859059802</submissionDate>
<transactionID>Test JUnit 3</transactionID>
</getReportsReturn>
</getReportsResponse>

SOAP API Scenario – Templates and Examples


Step 1: LogonManager
Before invoking the first provisioning command, you must request a token from the platform. To obtain this
token, the logon operation of the LogonManager Web service must be called.

Logon Request Template

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pm="http://soap.pm.gemalto.com">
<soapenv:Header/>
<soapenv:Body>
<pm:logon>
<pm:filename>... my properties file name here ...</pm:filename> <!--without extension-->
<pm:user>... my user id here ...</pm:user>
<pm:password>... my user password here ...</pm:password>
</pm:logon>
</soapenv:Body>
</soapenv:Envelope>

Parameters:
 Filename. The configuration file name (without the “.properties” suffix).
 user, password. The user account and password. This user must have sufficient rights to use
provisioning.

Logon Request Example

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pm="http://soap.pm.gemalto.com">
<soapenv:Header/>
<soapenv:Body>

35
36 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

<pm:logon>
<pm:filename>pm</pm:filename>
<pm:user>soapuser</pm:user>
<pm:password>soapuser_pwd</pm:password>
</pm:logon>
</soapenv:Body>
</soapenv:Envelope>

Logon Response Example

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<logonResponse xmlns="http://soap.pm.gemalto.com">
<logonReturn>
rO0ABXctEQAKYWRtZ2VtYWx0bxEADUFkbWluaXN0cmF0b3IAAAAAAAAAAAAAAAAAAAAA
</logonReturn>
</logonResponse>
</soapenv:Body>
</soapenv:Envelope>

Logon Error Response Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<soapenv:Fault>
<faultcode>soapenv:Server.userException</faultcode>
<faultstring>java.rmi.RemoteException: Unable to connect to server,
reporting:com.gemplus.gxs.internal.util.container.ServiceBreakdownException:
com.gemalto.pm.api.plugin.inputcntr.ws.WSInputConnectorWeb properties {gxs.product.name=LPM_AUTO,
pm.inputcntr.name=ws_auto}; nested exception is:
com.gemplus.gxs.internal.util.container.ServiceBreakdownException:
com.gemalto.pm.api.plugin.inputcntr.ws.WSInputConnectorWeb properties {gxs.product.name=LPM_AUTO,
pm.inputcntr.name=ws_auto}</faultstring>
<detail>
<ns1:hostname xmlns:ns1="http://xml.apache.org/axis/">fraisier</ns1:hostname>
</detail>
</soapenv:Fault>
</soapenv:Body>
</soapenv:Envelope>

Step 2: ProvisioningManager
The ProvisioningManager service provides the following operations:
 executeSynchronous, executeAsynchronous: to invoke all standard or custom LinqUs Provisioning
Manager commands, in synchronous or asynchronous mode
 getReport: to get commands’ end status.
To obtain the WSDL description use the following URL:
http://[hostname]:[port]/PM/services/ProvisioningManager?wsdl

Provisioning Request Template


executeAsynchronousCommand Request Template

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pm="http://pm.soap.pm.gemalto.com">
<soapenv:Header/>
<soapenv:Body>
<pm:executeAsynchronousCommand>
<pm:filename>... my properties file name here ...</pm:filename>
<pm:token>... my token here ...</pm:token>

36
37

<pm:command>
<![CDATA[
<Order>
<... My LPM standard or CUSTOM command here .../>
</Order>
]]>
</pm:command>
</pm:executeAsynchronousCommand>
</soapenv:Body>
</soapenv:Envelope>

Parameters:
 filename. The configuration file name (without the “.properties” suffix).
 Token. The token returned by the platform to authenticate the user (returned by the logon operation)
 command,. The XML standard or custom LinqUs Provisioning Manager command embedded into a
CDATA section.

getReport Request Template

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pm="http://pm.soap.pm.gemalto.com">
<soapenv:Header/>
<soapenv:Body>
<pm:getReport>
<pm:filename>... my properties file name here ...</pm:filename>
<pm:token>... my token here ...</pm:token>
<pm:invocationId>... my invocation id ...</pm:invocationId >
</pm:getReport>
</soapenv:Body>
</soapenv:Envelope>

Parameters:
 filename. The configuration file name (without the “.properties” suffix).
 token. The token returned by the platform to authenticate the user (returned by the logon operation).
 invocationId. The identifier of the invocation, specified in an executeSynchronousCommand or
executeAsynchronousCommand response.

getReports Request Template

<getReports xmlns="http://pm.soap.pm.gemalto.com">
<filename>… my properties file name here … </filename>
<token> … my token here … </token>
<invocationIds> … my invocation id1 …</invocationIds>
<invocationIds>… my invocation id2 …</invocationIds>
<invocationIds>… my invocation id3 …</invocationIds>
</getReports>

 filename. The configuration file name (without the “.properties” suffix).


 token. The token returned by the platform to authenticate the user (returned by the logon operation).
 invocationIds. The identifier of the invocation, specified in an executeSynchronousCommand or
executeAsynchronousCommand response. You can specify multiple invocationIds to return an array
of invocation results.

37
38 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Examples of Provisioning Requests


Asynchronous Command Request Example: createSubscription

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pm="http://pm.soap.pm.gemalto.com">
<soapenv:Header/>
<soapenv:Body>
<pm:executeAsynchronousCommand>
<pm:filename>pm</pm:filename>
<pm:token>
rO0ABXctEQAKYWRtZ2VtYWx0bxEADUFkbWluaXN0cmF0b3IAAAAAAAAAAAAAAAAAAAAA</pm:token>
<pm:command>
<![CDATA[
<Order>
<CreateSubscription
iccid="89492033603000015"
imsi="00894933603000015"
msisdn="33603000015"
initialState="ACTIVE"
cardProfile="GXX_v3.2_128K">
</CreateSubscription>
</Order>
]]>
</pm:command>
</pm:executeAsynchronousCommand>
</soapenv:Body>
</soapenv:Envelope>

Asynchronous Command Response Example: createSubscription

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/s"oap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<executeAsynchronousCommandResponse xmlns="http://pm.soap.pm.gemalto.com">
<executeAsynchronousCommandReturn>
<ID>496950</ID>
<endUser>soapuser</endUser>
<endingExecutionDate>0</endingExecutionDate>
<endingStatus>0</endingStatus>
<endingStatusLabel>NOT_AVAILABLE</endingStatusLabel>
<expirationDate>1206721977291</expirationDate>
<invoker>wsConnector1</invoker>
<processingDate>0</processingDate>
<resultData xsi:nil="true"/>
<serviceName>CreateSubscription</serviceName>
<state>1</state>
<stateLabel>SUBMITTED</stateLabel>
<submissionDate>1206721077291</submissionDate>
<transactionID></transactionID>
</executeAsynchronousCommandReturn>
</executeAsynchronousCommandResponse>
</soapenv:Body>
</soapenv:Envelope>

Response parameters:
 executeAsynchronousCommandReturn/ID: the return invocation id
 executeAsynchronousCommandReturn/endingStatusLabel: value “NOT_AVAILABLE” because we are
in an asynchronous command
 …

getReport Request Example

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pm="http://pm.soap.pm.gemalto.com">

38
39

<soapenv:Header/>
<soapenv:Body>
<pm:getReport>
<pm:filename>pm</pm:filename>
<pm:token>rO0ABXctEQAKYWRtZ2VtYWx0bxEADUFkbWluaXN0cmF0b3IAAAAAAAAAAAAAAAAAAAAA</pm:token>
<pm:invocationId>496950</pm:invocationId>
</pm:getReport>
</soapenv:Body>
</soapenv:Envelope>

getReport Response Example: SUCCEEDED createSubscription:

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<getReportResponse xmlns="http://pm.soap.pm.gemalto.com">
<getReportReturn>
<ID>496950</ID>
<endUser>soapuser</endUser>
<endingExecutionDate>1206721077448</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1206721977291</expirationDate>
<invoker>wsConnector1</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order
enduser="soapuser">
<CreateSubscription
iccid="89492033603000015"
imsi="00894933603000015"
msisdn="33603000015"
initialState="ACTIVE"
cardProfile="GXX_v3.2_128K">
<CreateSubscription>
</Order>
]]>
</resultData>
<serviceName>CreateSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1206721077291</submissionDate>
<transactionID xsi:nil="true"/>
</getReportReturn>
</getReportResponse>
</soapenv:Body>
</soapenv:Envelope>

Response parameters:
 state/stateLabel: the invocation state (IN_PROCESS/TERMINATED/ARCHIVED …)
 endingStatus/endingStatusLabel: the command ending status (SUCCEEDED/FAILED …)

Values and description of commands' state and status:


stateLabel state Description
CREATED 0 state of the invocation after creation

SUBMITTED 1 The invocation is accepted by the SEE server engine

IN_PROCESS 2 The invocation is currently processed

TRYING_TO_DEL 3 These states indicate someone (user or administrator) tries deleting


or suppressing the invocation. After a while, depending on server's
TRYING_TO_SUP 4 activity, the state will be TERMINATED and the ending status will be
DELETED or SUPPRESSED

TERMINATED 5 The invocation is terminated but not yet acknowledged

39
40 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

ARCHIVED 6 The invocation is terminated, and acknowledged (usually


automatically by input connector). Its ending status is FAILED or
EXPIRED. The invocation result is available for post-analysis

COMPLETED 7 The invocation is terminated and acknowledged. It is removed from


the invocation registry

UNKNOWN 8 unknown

endingStatusLabel endingStatus Description


NOT_AVAILABLE 0 The invocation is not terminated yet (the invocation is in process)

SUCCEEDED 1 Execution status OK

FAILED 2 The execution fails for any reason

EXPIRED 3 The expiration date has been reached during invocation processing

DELETED 4 The invocation was deleted by the user

SUPPRESSED 5 The invocation was deleted by the administrator

REJECTED 6 Failed due to a problem into internal server components. The


invocation could be replayed with success after an administrator's
(Not used by LPM)
action (replaced by FAILED in LPM)

UNREEXECUTABLE 7 Translated by LOST. Unable to replay invocations submitted without


GE but with GRD when the server restarts (possible cause: the SEE
(Not used by LPM)
has been interrupted before database update. The execution state
and ending status are uncertain. )
Such an invocation has to be manually replayed (replaced by
FAILED in LPM)

ABANDONED 8 The invocation execution failed due to a temporary situation. The


invocation could be replayed with success later (replaced by FAILED
(Not used by LPM)
in LPM)

MISSING_TARGET 9 Target unknown by the server (replaced by FAILED in LPM)


(Not used by LPM)

Synchronous Command Request Example Command: changeMSISDN

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:pm="http://pm.soap.pm.gemalto.com">
<soapenv:Header/>
<soapenv:Body>
<pm:executeSynchronousCommand>
<pm:filename>pm</pm:filename>
<pm:token>
rO0ABXctEQAKYWRtZ2VtYWx0bxEADUFkbWluaXN0cmF0b3IAAAAAAAAAAAAAAAAAAAAA</pm:token>
<pm:command>
<![CDATA[
<Order>
<ChangeMSISDN
iccid="89492033603000015"
msisdn="33603000555"
finalState ="ACTIVE"/>
</Order>
]]>
</pm:command>
</pm:executeSynchronousCommand>
</soapenv:Body>
</soapenv:Envelope>

40
41

Synchronous Command Response Example: FAILED changeMSISDN

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<executeSynchronousCommandResponse xmlns="http://pm.soap.pm.gemalto.com">
<executeSynchronousCommandReturn>
<ID>511254</ID>
<endUser>soapuser</endUser>
<endingExecutionDate>1207668342511</endingExecutionDate>
<endingStatus>2</endingStatus>
<endingStatusLabel>FAILED</endingStatusLabel>
<expirationDate>1207669242481</expirationDate>
<invoker>wsConnector1</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order
enduser="soapuser"
errorCode="100"
errorMessage="Card not found from iccid = &apos;89492033603000015&apos; !">
<ChangeMSISDN
iccid="89492033603000015"
msisdn="33603000555"
finalState="ACTIVE">
</ChangeMSISDN>
</Order>
]]>
</resultData>
<serviceName>ChangeMSISDN</serviceName>
<state>5</state>
<stateLabel>TERMINATED</stateLabel>
<submissionDate>1207668342481</submissionDate>
<transactionID/>
</executeSynchronousCommandReturn>
</executeSynchronousCommandResponse>
</soapenv:Body>
</soapenv:Envelope>

Response parameters:
 endingStatus/endingStatusLabel: the command’s end status (SUCCEEDED/FAILED)
 state/stateLabel: the invocation state (IN_PROCESS/TERMINATED/ARCHIVED)
 errorCode/errorMessage: the error that occurred. For more information about error codes, see Appendix
A.

Synchronous Command Response Example: getSubscriptionInformation by iccid

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<executeSynchronousCommandResponse xmlns="http://pm.soap.pm.gemalto.com">
<executeSynchronousCommandReturn>
<ID>28457003</ID>
<endUser>soapuser</endUser>
<endingExecutionDate>1218546415441</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1218547315124</expirationDate>
<invoker>wsConnector1</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order
enduser="soapuser">
<GetSubscriptionInformation
iccid="89492033603000013">
<dm

41
42 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

subscription_status="unknown"></dm>
<pb
subscription_status="missing"></pb>
<ota
imsi="00894933603000013"
msisdn=""
profile_name="GXX_v3.2_128K"
card_state="0"
subscription_status="present"
iccid="89492033603000013">
<applets>
<applet
sd="A000000018434D08090A0B0C000000"
label="RAM applet instance"
aid="A000000018434D08090A0B0C000000"
state="2"></applet>
<applet
sd="A000000018434D08090A0B0C000000"
label="RFM applet instance"
aid="A00000001803090000000000B00010"
state="2"></applet>
</applets>
</ota>
<ddm
imei="3579720003000013"
subscription_status="present"></ddm>
<sm
service_content_status="Unknown"
msisdn=""
portal_name="empty"
service_profile_name="empty"
subscription_status="present"
simcard_status="Unknown"
iccid="89492033603000013"></sm>
</GetSubscriptionInformation>
</Order>
]]>
</resultData>
<serviceName>GetSubscriptionInformation</serviceName>
<state>5</state>
<stateLabel>TERMINATED</stateLabel>
<submissionDate>1218546415124</submissionDate>
<transactionID/>
</executeSynchronousCommandReturn>
</executeSynchronousCommandResponse>
</soapenv:Body>
</soapenv:Envelope>

getReports Request Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<getReports xmlns="http://pm.soap.pm.gemalto.com">
<filename>pm</filename>
<token>rO0ABXdCAAABJvau9B8RAAphZG1nZW1hbHRvEQANQWRtaW5pc3RyYXRvcgAAAAAAAAAAAAAAAAAAAAAC
AAAAAAAAASb2rqrBdAAMRXVyb3BlL1Bhcmlzdw4AAAADAQAAAAASAAAAFHcUx8wygHyVXwGP5MiGS8ZlpvnvGmM=</token>
<invocationIds>271062</invocationIds>
<invocationIds>271063</invocationIds>
<invocationIds>271064</invocationIds>
</getReports>
</soapenv:Body>
</soapenv:Envelope>

getReports Response Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<getReportsResponse xmlns="http://pm.soap.pm.gemalto.com">
<getReportsReturn>
<ID>271062</ID>
<endUser>admgemalto</endUser>

42
43

<endingExecutionDate>1266859057316</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1266859946439</expirationDate>
<invoker>ws_auto</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order transactionId=”Test Unit” enduser=”admgemalto”>
<DeleteSubscription iccid=”12345123451234”></DeleteSubscription></Order>
]]>
</resultData>
<serviceName>DeleteSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1266859046439</submissionDate>
<transactionID>Test JUnit</transactionID>
</getReportsReturn>
<getReportsReturn>
<ID>271063</ID>
<endUser>admgemalto</endUser>
<endingExecutionDate>1266859059673</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1266859957610</expirationDate>
<invoker>ws_auto</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order transactionId=”Test Unit” enduser=”admgemalto”>
<DeleteSubscription iccid=”12345123451236”></DeleteSubscription></Order>
]]>

</resultData>
<serviceName>DeleteSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1266859057610</submissionDate>
<transactionID>Test JUnit 2</transactionID>
</getReportsReturn>
<getReportsReturn>
<ID>271064</ID>
<endUser>admgemalto</endUser>
<endingExecutionDate>1266859062695</endingExecutionDate>
<endingStatus>1</endingStatus>
<endingStatusLabel>SUCCEEDED</endingStatusLabel>
<expirationDate>1266859959802</expirationDate>
<invoker>ws_auto</invoker>
<processingDate>0</processingDate>
<resultData>
<![CDATA[
<Order transactionId=”Test Unit” enduser=”admgemalto”>
<DeleteSubscription iccid=”12345123451237”></DeleteSubscription></Order>
]]>

</resultData>
<serviceName>DeleteSubscription</serviceName>
<state>6</state>
<stateLabel>ARCHIVED</stateLabel>
<submissionDate>1266859059802</submissionDate>
<transactionID>Test JUnit 3</transactionID>
</getReportsReturn>
</getReportsResponse>
</soapenv:Body>
</soapenv:Envelope>

The getReports Error Response Example


If the number of invocation IDs exceeds the maximum limit, the server will return an error to the client. And
an example of error message is as following:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<soapenv:Fault>
<faultcode>soapenv:Server.generalException</faultcode>

43
44 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

<faultstring>The reports size exceeds the maximum limit 100; nested exception
is: java.lang.IllegalArgumentException</faultstring>
<detail/>
</soapenv:Fault>
</soapenv:Body>
</soapenv:Envelope>

3
Batch Files

Using the Batch connector


A LinqUs Provisioning Manager batch file is a sequence of provisioning orders. Several different types of
provisioning command can be contained in a single batch file, however it is recommended to not insert
several provisioning commands for the same subscriber in the same file.
For batch file processing details, refer to the LinqUs Provisioning Manager Administration Guide.

Retrieving XSD Files


The dedicated XSD schema files that validate batch files, can be retrieved from the config/ folder of the
LinqUs Provisioning Manager server instance tree (<linqus_home>/PM/<PM_instance_name>/config):
pmCommands.xsd
pmBatchFile.xsd (validates batch commands, and includes previous file)
custom/pmCommands_CUSTOM.xsd (included in previous file)
XSD files and examples files are also provided in a Zip file, available with the product documentation.

Example of a batch file (provisioning OTA only):


<?xml version="1.0" encoding="ISO-8859-1" ?>
<ProvisioningOrders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.gemalto.com/schema/pm pmBatchFile.xsd"
xmlns="http://www.gemalto.com/schema/pm" generateReport="true">

<Order transactionId="BatchTrans01">
<CreateSubscription
iccid ="8949200624034289"
imsi ="0089490624003259"
msisdn ="06240003129"
initialState ="ACTIVE"
cardProfile ="GXX_v3.2_128K">
</CreateSubscription>
</Order>

<Order transactionId="BatchTrans02">
<CreateSubscription
iccid ="8949200624001832"

44
45

imsi ="0089490624013421"
msisdn ="0624001223"
initialState ="ACTIVE"
cardProfile ="GXX_v3.2_128K">
</CreateSubscription>
</Order>

<Order transactionId="BatchTrans03">
<CreateSubscription
iccid ="8949200624001835"
imsi ="0089490624013422"
msisdn ="0624001226"
initialState ="ACTIVE"
cardProfile ="GXX_v3.2_128K">
</CreateSubscription>
</Order>

<Order transactionId="BatchTrans04">
<CreateSubscription
iccid ="8949200624001837"
imsi ="00894906240134222"
msisdn ="0624001228"
initialState ="ACTIVE"
cardProfile ="GXX_v3.2_128K">
</CreateSubscription>
</Order>

</ProvisioningOrders>

Example of a batch file (provisioning OTA and SRM):


<?xml version="1.0" encoding="ISO-8859-1" ?>
<ProvisioningOrders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.gemalto.com/schema/pm pmBatchFile.xsd"
xmlns="http://www.gemalto.com/schema/pm" generateReport="true">

<Order transactionId="BatchTrans01">
<CreateSubscription
iccid ="8949200624034289"
imsi ="0089490624003259"
msisdn ="06240003129"
initialState ="ACTIVE"
cardProfile ="GXX_v3.2_128K">

<SubscribeTo>
<Capabilities>
<Capability key="Prepaid" value="false"/>
<Capability key="Postpaid" value="true"/>
</Capabilities>
<SubscribedOptions>
<SubscribedOption name="NFC" state="ACTIVATED"/>
</SubscribedOptions>
</SubscribeTo>

</CreateSubscription>
</Order>

Batch reports
LPM Batch reports are xml files, which format is fully compatible with batch input format.
A batch report file can be replayed.

This report provides error details for each failed command (errorCode/errorMessage/subErrorMessage)
Succeeded commands are reported with submission information and without an error code.

45
46 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Batch report example:

<?xml version="1.0" encoding="UTF-8"?>


<ProvisioningOrders generateReport="true">

<Order
transactionId="Trans33650000000"
submissionDate="2008/04/10 10:26:57:810"
endingDate="2008/04/10 10:26:57:922"
submissionInfo="0@CR_ICCID_INACTIVE_10_3Errors_report_20080410_102657">
<CreateSubscription
iccid="89492033650000000"
imsi="008933650000000"
initialState="INACTIVE"
cardProfile="GXX_v3.2_128K"></CreateSubscription>
</Order>
<Order
transactionId="Trans33650000001"
errorCode="13"
errorMessage="The card profile &apos;GX3G_v2.2_128K&apos; is unknown :
com.gemplus.gxs.api.exception.NoMatchingObjectException: Unable to find &apos;CardProfile&apos;
identified by &apos;name&apos; = &apos;GX3G_v2.2_128K&apos;. "
subErrorMessage="com.gemplus.gxs.api.exception.NoMatchingObjectException: Unable to find
&apos;CardProfile&apos; identified by &apos;name&apos; = &apos;GX3G_v2.2_128K&apos;. "
submissionDate="2008/04/10 10:26:57:863"
endingDate="2008/04/10 10:26:57:957"
submissionInfo="1@CR_ICCID_INACTIVE_10_3Errors_report_20080410_102657">
<CreateSubscription
iccid="89492033650000001"
imsi="008933650000001"
initialState="INACTIVE"
cardProfile="GX3G_v2.2_128K"></CreateSubscription>
</Order>
<Order
transactionId="Trans33650000009"
errorCode="13"
errorMessage="The specified group &apos;062331&apos; is unknown. :
com.gemplus.gxs.api.exception.NoMatchingObjectException: Unable to find &apos;CardGroup&apos;
identified by &apos;id&apos; = &apos;062331&apos;. Unable to add cards."
subErrorMessage="com.gemplus.gxs.api.exception.NoMatchingObjectException: Unable to find
&apos;CardGroup&apos; identified by &apos;id&apos; = &apos;062331&apos;. Unable to add cards."
submissionDate="2008/04/10 10:26:58:339"
endingDate="2008/04/10 10:26:58:391"
submissionInfo="9@CR_ICCID_INACTIVE_10_3Errors_report_20080410_102657">
<CreateSubscription
iccid="89492033650000009"
imsi="008933650000009"
initialState="INACTIVE"
cardProfile="GXX_v3.2_128K"
groupId="062331"></CreateSubscription>
</Order>
<Order
transactionId="Trans33650000003"
submissionDate="2008/04/10 10:26:57:983"
endingDate="2008/04/10 10:26:59:007"
submissionInfo="3@CR_ICCID_INACTIVE_10_3Errors_report_20080410_102657">
<CreateSubscription
iccid="89492033650000003"
imsi="008933650000003"
initialState="INACTIVE"
cardProfile="GXX_v3.2_128K"></CreateSubscription>
</Order>
</ProvisioningOrders>

46
47

4
Error Messages

The following errors may appear in batch reports.

Error Code Exception Name Description

PM-1 UnMappedException Unhandled error

PM-10 UnknownCommandException Unknown provisioning command

PM-11 CommandHandlingException Error occurred during command execution

PM-12 MissingParameterException Mandatory command parameter is missing

PM-13 InvalidCommandParameterException Command parameter is invalid

PM-14 InconsistentCommandParameterException Inconsistent subscription identification.


Products are not provisioned with the same
values
PM-15 InconsistentSubscriptionInProductsException Inconsistent subscription between products
PM-100 SubscriptionDoesNotExistException Subscription does not exist on product
PM-101 SubscriptionAlreadyExistException Subscription already exists on product
PM-102 AlreadyAllocatedMsisdnException MSISDN already allocated to another card
PM-103 AlreadyAllocatedImsiException IMSI already allocated to another card
PM-1000 XMLParsingException General XML parsing exception
PM-10000 InvalidProvisionedProductConfigException Invalid provisioned product configuration. A
trigger may not be activated
PM-10001 UtilityConnectorDeactivatedException Connection to a targeted product is
deactivated
PM-10002 UtilityConnectorDisconnectedException Connection to a targeted product is down
PM-10003 UtilityConnectorProductAccessException Access to the targeted product has failed
PM-10004 UtilityConnectorProductInvocationException Unable to request service execution on a
product
PM-10005 FileTransferException File transfer to product has failed
PM-10006 MaxLockLimitReachedException Unable to accept the new invocation as the
maximum number of locks has been
reached
PM-10007 LockRequestException Unable to set the locks requested by the
command
PM-10008 TemporaryCommandHandlingException Unable to accept the new command
execution due to a temporary internal error.

47
48 LinqUs Provisioning Manager 5.2 Command Parameters Reference Guide

Server is probably busy


PM-10009 ProductExecutionException A product has returned an error, caused by
an external resource usage, while executing
an operation requested by a provisioning
command
PM-10200 SubscriptionNotDeletedException Subscription has not been deleted on
product
PM-10201 SubscriptionNotInactivatedException Subscription has not been inactivated on
product
PM-10202 SubscriptionNotUpdatedException Subscription has not been updated on
product
PM-10203 IllegalSubscriptionException Subscription state found on product is
incompatible with requested command
operation
PM-10204 SubscriptionNotActivatedException Subscription has not been activated on
product
PM-10210 LockedSubcriptionException Command has tried to execute an action on
a card locked by a product. Server has
refused the requested action
PM-10300 OTACardNotDeletedException SIM card has not been deleted on OTA
Manager server
PM-10301 OTACardNotInactivatedException SIM card has not been inactivated on OTA
Manager server
PM-10302 OTACardNotUpdatedException SIM card has not been updated on OTA
Manager server
PM-10303 OTACardNotActivatedException SIM card has not been activated on OTA
Manager server
PM-11000 ConnectionException (Web service client) Report that the Web service application is
not granted to access server. Check that
the user used by the Web service
application has the necesary access rights
to the server
PM-11001 ConnectionException (Web service client) Report that the Web service application
cannot access the required connector on
the server side
PM-11002 ConnectionException (Web service client) Report that the Web service end user has
provided an invalid session token
PM-12000 AccessDeniedException (Core API client) Report that the connected client does not
have the necessary access rights to
perform the operation
PM-12001 CommandMonitoringException (Core API Command manager has encountered a
client) problem while performing the operation

48