01-EVC SMOI User Manual Body

User Manual EVC Service Management Open Interface
Table of Contents
Table of Contents
Chapter 1 SMOI Protocol .............................................................................................................. 1-1 1.1 Introduction to the SMOI protocol ...................................................................................... 1-1 1.2 Networking Mode of SMP .................................................................................................. 1-1 1.3 Architecture of SM Interface .............................................................................................. 1-2 1.4 Program of SM Interface.................................................................................................... 1-2 1.5 MML Commands................................................................................................................ 1-3 1.5.1 Format of MML Commands .................................................................................... 1-3 1.5.2 Character Set for MML Commands ........................................................................ 1-6 1.5.3 MML Syntax ............................................................................................................ 1-7 1.6 Standard Interface Software .............................................................................................. 1-9 1.6.1 Software Architecture .............................................................................................. 1-9 1.6.2 Relationship between Standard Interface Software.............................................. 1-11 1.7 Security Management of SMP ......................................................................................... 1-11 1.7.1 Overview ............................................................................................................... 1-11 1.7.2 Access Security..................................................................................................... 1-11 1.7.3 Operation Security ................................................................................................ 1-12 1.7.4 Data Security......................................................................................................... 1-12 Chapter 2 SMOI Program Operation............................................................................................ 2-1 2.1 Connection......................................................................................................................... 2-1 2.2 Message ............................................................................................................................ 2-1 2.2.1 Service Message Code(V1.00) ............................................................................... 2-1 2.2.2 Service Message Code(V1.01) ............................................................................... 2-5 2.2.3 Heartbeat Message................................................................................................. 2-6 2.2.4 Timeout Judgment .................................................................................................. 2-6 2.3 Format of a Message through the SMP Interface.............................................................. 2-7 2.4 MML Command Format..................................................................................................... 2-8 2.4.1 MML Command....................................................................................................... 2-8 2.4.2 Command Code ...................................................................................................... 2-8 2.4.3 Parameter Block...................................................................................................... 2-9 2.4.4 Character Set in MML Command.......................................................................... 2-11 2.5 MML Grammar................................................................................................................. 2-12 2.5.1 Identifier................................................................................................................. 2-12 2.5.2 Numerical Value .................................................................................................... 2-13 2.6 MML Features.................................................................................................................. 2-14 2.6.1 Batch Operation .................................................................................................... 2-14 2.6.2 Confirmation Prompt ............................................................................................. 2-15 2.7 Interaction between BSS/OSS and SMP......................................................................... 2-15
Huawei Technologies Proprietary i
Table of Contents
2.7.1 Procedure.............................................................................................................. 2-15 2.7.2 Information Flow.................................................................................................... 2-16 Chapter 3 Commonly-Used MML Command Set........................................................................ 3-1 3.1 Interface Description.......................................................................................................... 3-1 3.1.1 Parameter Description ............................................................................................ 3-1 3.1.2 Special Note ............................................................................................................ 3-2 3.2 Common Errors.................................................................................................................. 3-3 3.3 Service Center (EVC) ........................................................................................................ 3-4 3.3.1 Logging in................................................................................................................ 3-4 3.3.2 ACK of Logging in ................................................................................................... 3-4 3.3.3 Logging out.............................................................................................................. 3-5 3.3.4 ACK of Logging out ................................................................................................. 3-6 3.4 EVC Service....................................................................................................................... 3-6 3.4.1 Modifying AD Stock................................................................................................. 3-6 3.4.2 ACK of Modifying AD Stock .................................................................................... 3-7 3.4.3 Suspending an RS .................................................................................................. 3-8 3.4.4 ACK of Suspending an RS...................................................................................... 3-8 3.4.5 Adding an RS .......................................................................................................... 3-9 3.4.6 ACK of Adding an RS............................................................................................ 3-10 Acronyms and Abbreviations ......................................................................................................A-1
Huawei Technologies Proprietary ii
Chapter 1 SMOI Protocol

1.1 Introduction to the SMOI protocol
This manual describes the interface protocol between service management point (SMP) and Medial Device (MD), and the Man-Machine Language (MML) commands supported by the system. SMP software provides an open interface protocol, whose main contents consist of standard MML commands. Thus, MD can communicate with SMP through MML commands and receive the operation result returned by SMP. Any third-party manufactured access device abiding by this interface protocol can operate SMP.
1.2 Networking Mode of SMP

The networking mode of SMP and business hall terminal is illustrated in Figure 1-1.
SCP
SMP
MD:SMOI /Local Server
MD:SMOI /WEB SERVER
MD:SMOI /Bank Interface
Business Hall Terminal
Browser
Bank
Figure 1-1 Networking mode of SMP with outer entities The outer terminal can be connected to SMP with MD. Service Management (SM) interface protocol applies to MD and SMP, whereas the protocol applying to MD and outer entities shall be defined by the operator. In this case, MD is regarded by SMP as the terminal with SM interface.
Huawei Technologies Proprietary 1-1
1.3 Architecture of SM Interface

For the protocol about the interaction of SMP with the terminal, refer to section 1.6 "Interaction between MD and SMP. The lower layer of SM interface adopts TCP/IP protocol. The interface protocol stack is shown in Figure 1-2.
SMP SM Interface protocol layer TCP/IP Physical layer
MD SMOI SM Interface protocol layer TCP/IP Physical layer
Figure 1-2 SM interface protocol stack Before MD and SMP send messages, the TCP/IP connection with SMP must first be established. When MD no longer needs to interact with SMP, the SOCKET connection with SMP will be released. In case of IDLE, it needs to remain the connection with SMP by sending heartbeat messages. The maximum number of connections that can be established between SMP and each MD correlates to SMP hardware processing capability. The minimum number of connections supported by SMP is 250.
1.4 Program of SM Interface

The interface program running on MD is SMOI, which is a console program and functions to provide interface for command lines. Its prompt is a single great sign with the current dialog ID and the current transaction ID. (For example, 1 3 SMOI>). It can read and transfer commands from standard input terminal and display the messages returned by SMP on standard output terminal. SMOI program is operated in asynchronous mode and multiple MML commands can be input at one time. The sequence of input commands may differ from that of the returned messages. For the operation on SMOI program interface, refer to Chapter 2, SMOI Program Operation.
1.5 MML Commands

1.5.1 Format of MML Commands
I. Overview
An MML command begins with a command code. It specifies what the system needs to execute. Its additional information is expressed by its parameters tailed, which are separated from the command code by colon (:) at the end of a command code. Parameters are defined by parameter block. Multiple commands are separated by semicolons (;), which can be omitted in the case of single command involved, as shown in Figure 1-3.
Command Code
...
Parameter Block
Figure 1-3 Format of MML command
II. Command code

Command code consists of command prefix and body. It is not case-sensitive. Prefix is used to identify whether this command is an ACK or not. Prefix is separated by colon (:) from the command body. Prefix has other two forms: MON -meaning a detecting command, and NOTIFY -meaning a notification message. Prefix MON has not yet been provided currently. Command body can only have a maximum of 3 identifiers, and each of them is separated by space, as shown in Figure 1-4.
command
identifier1
sp
identifier2
sp
identifier3
Figure 1-4 Format of MML command code Meaning of each command code:
Identifier 1: Identifier with a maximum length of 8-character. It stands for executive action, such as ADD, DISP, MODI and CREATE. Identifier 2: Identifier with a maximum length of 8-character. It stands for the service name at which this executive action enforces, such as PPS. Identifier 3: Identifier with a maximum length of 8-character. It stands for the object entity of executive actions, such as ACNT and OPER. For example, to list PPP accounts: DISP PPS ACNTINFO: MSISDN= 11990000
III. Parameter block

Parameter block contains the information required by the specific functions of the executive commands. This information is specified by some specific parameters according to a certain command. Parameter blocks, including more than one parameter, are separated by commas (,). All parameters are defined according to its name. Also, the input sequence of the parameters by user does not influence the commands executing result. Definition of parameters A parameter consists of a name and its value, separated by an equal mark (=). In the case of omitting a given parameter, its considered that a default value has been designated. Or, its OK to specify a given parameter value to represent the default value. If there is not any valid character between the equal mark and comma after the parameter name, then default parameter will also be used. Parameter name Parameter name consists of a maximum of 16 characters. It is not case sensitive. Parameter value Parameter value is composed of an information unit or a compound of information units. Information unit The composition of an information unit is shown in Figure 1-5

Identifier Decimal Date Time String
Figure 1-5 Composition of an information unit Compound information unit Assemble several information units into a compound, and then we can input more than one information unit to a single parameter. Here, the assembling of compound units will not be considered. The assembling of information units mentioned hereafter all refer to the combination of simple information units, instead of compound information units. The way to specify several information units within one parameter is to delimit these values by using &. For example, 5&9 represents the compounding of unit 5 and 9. To represent an information unit of continuous sequence (increment=1), simply specify the lowest and highest information units and insert mark && between them. For example, "5&&9" stands for information units: "5,6,7,8,9". "N 11990000 &&N 11990999" stands for the number segment with 1,000 numbers. Refer to relevant MML commands to determine whether && marks are supported. The assembling number is decided by the size of a single message within a protocol. The current size is 64KB. Default parameters Parameters in an MML command can be requisite parameters, optional parameters and default parameters. Requisite parameters can not be omitted when the command is executed, optional parameters can be chosen to input by the user, and default parameters will be provided automatically by the system in case there is no parameter input. Obey the rules below to use the default parameters: As long as a default value can be given, the parameter shall be specified as a default parameter (for example, when adding a user, even non-key parameter can be designated with a default value). The value of a default parameter shall be unique within the same command. A default parameter can take different values in different commands. The same default parameter in different commands can have different values.
Default value should be the one used in most cases. Example of MML command Modify the subscribers balance: MODI PPS BALANCE: MSISDN=, INCRMENT= ACK: MODI PPS BALANCE:RETN=,DESC=[ORGBALANCE=,LASTBALANCE=]
1.5.2 Character Set for MML Commands

I. Alphabet
All alphabet characters (upper case or lower case) and characters * and # are included.
II. Digit
All decimal characters (0 to 9), are valid.
III. Delimiter
The following marks are used to separate different units of an input session. Colon (:): separates the first parameter from the command code or command name. Equation (=): separates the first value from the parameter name or parameter code. Comma (,): separates different parameters. Ampersand (&): separates all of the values for a parameter. Double-ampersand (&&): separates the lower limitation value from the upper one in a parameters value range. Apostrophe (): separates the valued-indicator from its value. Semicolon (;): separates different commands.
IV. Number scale

B O D H N Binary system Octal system Decimal system Hexadecimal system Numerical string
V. Special character
Double-quote (): separates a string from some context in a memo sign. Space: separates command code and to improve readability as well. Enter: not to be used in the system, but can be adopted to improve readability. Star(*) Pound(#) Hyphen (-)
1.5.3 MML Syntax

I. Identifier
Identifier is a string consisting of one or multiple characters. It is headed by an alphabet or underline and followed by one or more digits, alphabets or underlines. For example, UPDATE and NO7 are valid identifiers.
Digit Alphabet/Underline Alphabet or Underline
Figure 1-6 Identifier
II. Number
Decimal number Decimal number consists of an array of digital characters, which are preceded by characters D to identify themselves. If the default number scale is decimal, characters D can be omitted.
D'
Digit
Figure 1-7 Decimal number Numerical string Numerical string can be used to express some information, which are composed of digital characters, but cannot be expressed by decimal numbers. For instance, MSISDN and the PPS card number.
N'
Digit
Figure 1-8 Numerical string Character string Character string (or context) permits inputting literal characters, including any delimiter, which will have its grammar meanings when input outside this character string. Character string is composed of zero to several characters, and bracketed with one double-quote () at either end. Character string includes all valid characters, and if double-quote () appears in a sting, it shall follow a backslash.
Character (excluding ") " "
Figure 1-9 Character string
III. Date
Date is expressed by digits, with double-quote () at both ends. It shall follow such sequence as year, month, and day. Year is a 4-digit decimal number, while month and day are 2-digit decimal numbers. There shall be hyphens between year and month, and between month and day. For example: 1999-01-16.
IV. Time
The 24-hour timing system is adopted here, with double-quote () at both ends of the time. The sequence is from left to right: hour, minute, and second. Hour is a 2-digit decimal number, ranging from 00 to 23 (23 included). Minute and second are both 2-digit decimal numbers, ranging from 00 to 59 (59 included). For example: 12:25:01.
V. Date and time

Date and time is expressed with a space between them. For example: 1999-01-16 12:25:01. Interaction between MD and SMP
Figure 1-10 shows the complete procedure of the interaction of MD with SMP. The handling of abnormal circumstances and the process of setting up multiple dialogs are omitted here.
Start
Establish SOCKET connection with SMP
Succeed? Yes Send LOGIN command Send the first MML command SMP returned successfully? Yes Get session ID All sent out? No No Transaction ID+1 No Send the next MML command Yes Transaction over? Yes Execute operation No Wait until all the branches are finished No more operation? Yes Operation end Receive MML ACK Operation start
Parellel operation
No
Send LOGOUT command
End
Figure 1-10 Procedure of the interaction of MD with SMP
1.6 Standard Interface Software

1.6.1 Software Architecture
The standard interface software consists of multiple processes, each of which is of layer structure, such as mechanism layer and application layer. The mechanism is to
extract the public part of the system for the use of the application layer. To put it in another way, the mechanism has little relationship with specific applications. The inside of the mechanism can be divided into further layers according to requirements. Related functions (category) can be packed into one package. Different packages may depend on each other. Each layer of the mechanism may be composed of one or multiple packages. The structure of each process is shown in Figure 1-11.
Application layer Log and alarm monitoring management layer Configuration management layer Session, transaction mechanism layer Communication mechanism layer Scheduling mechanism layer
Figure 1-11 Sketch map of the layer structure of processes The brief introduction to each layer is as follows: Scheduling mechanism layer: Completes the function of scheduling and providing clock, and provides parallel operation capability. Communication mechanism layer: This layer is above the scheduling mechanism layer, and achieves reliable communication. Above the scheduling mechanism layer is the communication mechanism layer: Mainly functions to achieve reliable communication. Session and transaction mechanism layer: This layer is above communication mechanism layer: For business terminal, system will set up a session when the operator logs in. Sessions will also be established among different services, similar to an interaction environment between them Service-side session consists of several transactions, and each transaction consists of several operations, and each operation equals to an MML command. Configuration management mechanism layer: This layer is above the session and transaction mechanism layer and completes the functions of registration, application, and dynamic management of each service. Log and alarm monitoring management layer : This layer is above the configuration management mechanism layer. Application layer: This layer is established above the mechanism and makes use of the services provided by the mechanism.
1.6.2 Relationship between Standard Interface Software

To realize SM interface, the following system processes are necessary: client access agent process, service configuration management process, external entity agent process, and application service process. Client access agent process provides standard protocol interface to the outside, and is the only path that peripheral access device with standard protocol interface can operate on SMP. Service configuration management process mainly functions to achieve the dynamic configuration, operator login, and operator management of each service. External entity agent process is the only path through which system interacts with external entities. External entities mainly include SCP, Informix database and so on. Application service process is in charge of completing the real tasks accomplished by SMP, such as the various operations of PPS (the prepaid service).
1.7 Security Management of SMP

1.7.1 Overview
To ensure the security of system and convenience of operation, system shall provide the security management function for device access and setting user operation authority, which includes access security management, security management of various operators, and security management of system supervisor (referred to as operator hereafter). The system will perform operator authority management both from operation authority and from data authority. Relevant authority parameters will be set for each module and function operation. In real cases, we shall determine the operator security before setting the operation authority.
1.7.2 Access Security

SMP access security includes two indices: number of on-line subscriber and how busy the system is. The system will decide whether to allow new user to log in or new external device to access, depending on the number of currently logged-in users and the occupancy of CPU and the IO of disk.
1.7.3 Operation Security

SMP shall perform authentication for the commands sent by the operator. And the commands sent by operator without authority will be returned with error information.
1.7.4 Data Security

SMP shall not only perform authentication for the commands sent by the operator, but also check the data security for the data processed by the operator. The latter also concerns the function operation. To make judgment on the data security, operators of higher authority can process the data that are able to be handled by operators of lower authority.
Chapter 2 SMOI Program Operation

2.1 Connection
TCP/IP SOCKET connection must be established when SMP client communicates with SMP and then released after interaction. In idle state, heartbeat message is required to connect SMP client and SMP.
2.2 Message
Service message based on the SMP open interface protocol is the smallest unit to transfer operative information of users. When the connection is established, the client sends an MML command to SMP after transaction ID of the session is determined, and then decodes received packets. Format of message involved in this process is determined by the SMP open interface protocol. See the figure below for the structure of messages transmitted through SMP open interface.
Message start flag Checksum Operative Transaction Session information header header Message header Message length Message start flag
Message sending sequence
Heartbeat message over SMP open interface protocol is used to detect the connection between the client and SMP. It is sent 180 s (configurable) later when the connection is idle. See the figure below for the structure of heartbeat message.
Checksum Content Message length Message start flag
Message sending sequence
2.2.1 Service Message Code(V1.00)

This Version number is 1.00. Code of parameter configured over SMP open interface protocol must conform to the following rules: For the integral of 16 or 32 bits in hexadecimal format, you must fill with blank spaces when the character string cannot reach the specified length.
I. Message start flag (4 Bytes)

It denotes the start and end of a message. Length: 4 Byte Code: `SC `
II. Message length (4 Bytes)

It denotes the total length of the interval between the message header and operative message. Its value is denoted by an integral of 4 bytes in hexadecimal format ranging from 0-65535 (0000-FFFF).
III. Message header (20 Bytes)

It contains the following parameters: -----Version number: It denotes the version of SMP open interface protocol with the code of 4 Octet character strings. The current version number is 1.00. -----Terminal identifier: It is denoted by 8 Octet character strings to identify the front end processor and terminal of BSS/OSS accessed to SMP. By the use of it, SMP can judge whether the terminal user accessed is legal. For example, it can used to configure terminals requiring precedent access. Note: Terminal identifier of the front end processor in BSS/OSS must be contained in the message header in case of initial access, because SMP performs authentication only to the terminal identifier of front end processor. From then on, the terminal identifier of a specific terminal must be filled in. Coding rule of terminal identifier is determined by the network. -----Service name: It denotes the service that the operator applies for, and its code is composed of 8 Octet character strings. The service name is specified in MML commands. See the following service names. FS: File service LOG: Log service RPT: Report service OPRM: Operator management SRVM: SMP versatile services
IV. Session header (18 Bytes)

Session is a virtual connection (logical connection) between SMP and BSS/OSS accessed and also a unique identifier of a valid login. With the identifier of session ID, BSS/OSS originates a virtual connection to SMP. Session ID over the same SOCKET connection cannot repeat. One or more sessions can be established based on one connection between BSS/OSS and SMP. MML commands can be sent through the session newly established when the message of login success is received from SMP. Execute the logout command to notify SMP to clear information of the session when the session is not required. Session header consists of session ID, session control characters and reserved field. -----Session ID: It is denoted by an integral of 32 bits (8 Byte) in hexadecimal format starting with 1. With its value larger than 0, session ID is the unique identifier of each session originated by BSS/OSS. It varies with the session. In the front end processor of BSS/OSS, TCP connection (physical connection) and session (logical connection) ID are used to determine the path for sent messages (The login ID can be used as session ID if one logical connection corresponds to one physical connection.). -----Session control character: It is denoted by 6 Octet character strings (6 Byte). Codes of session control character are shown as follows: DlgLgn: Login request DlgCon: Session hold DlgEnd: Session end By the use of session control character, DlgLgn, DlgCon are filled respectively for login, message transmission. When BSS/OSS sends the logout message, SMP return the Message filled DlgEnd. -----Reserved field: It is of 4 Bytes used for subsequent extended services.
Reserved field Session control character Session ID
Bit sending sequence
V. Transaction header (18 Bytes)

Transaction contained in a session refers to a deal between SMP and BSS/OSS accessed. It involves one or more MML commands (contained in one or more messages) and the result of it is contained in one or more MML ACK commands. Based on the session, BSS/OSS sends messages to SMP to execute various operations, thereby implementing the function of service management. According to
the number of MML and MML ACK commands, the function can be classified as that single or multiple messages can be returned when single command is sent. Transaction ID is managed by BSS/OSS to identify MML command and MML ACK in different operations (An operation is taken as a deal.), and it is unique when used in a session. Transaction header consists of the following parts: ------Transaction ID: It is denoted by an integral of 32 bits in hexadecimal format starting with 1. Transaction ID with the value larger than 0 is allocated by the client (BSS/OSS) to identify a transaction. In the same session, they are different from each other. ------Transaction control character: It is denoted by 6 Octet character strings (6 Byte). TxBeg: Transaction start TxCon: Transaction proceed TxEnd: Transaction end ------Reserved field: It is of 4 Byte used for subsequent extended services.
Note: SMP keeps the result obtained from an operation for certain a period that can be configured.
VI. Operative information

It denotes MML commands executed. See Chapter 3 for the format of MML command. Fill with blank spaces if the length of MML command is not the multiple of 4.
VII. Checksum (8 Bytes)

It is denoted by an integral (8 Byte) of 32 bits in hexadecimal format. The calculation algorithm of checksum is shown as follows. Perform XOR for Message header + Session header + Transaction header + Operative information as 32 Byte, and the inverse of result obtained from XOR is the checksum. SMP disables the check of checksum when interfaces are tested.
2.2.2 Service Message Code(V1.01)

This Version number is 1.01. It keeps the same with version 1.00 except for added languages in coding MML messages. And SMP can handle MML messages in version 1.00 and 1.01 simultaneously.
I. Message start flag (4 Byte)

It denotes the start and end of a message. Length: 4 Byte Code: `SC `
II. Message length (4 Bytes)

It denotes the total length of the interval between the message header and operative message.
III. Message header (28 Bytes)

Message header contains the following parameters: -----Version number: It denotes the version of SMP open interface protocol with the code of 4 Octet character strings. Current version number is 1.01. -----Terminal identifier: It is denoted by the code of 8 Octet character strings to identify the front end processor and terminal of BSS/OSS accessed to SMP. -----Service name: It denotes the service that the operator applies for, and its code is composed of 8 Octet character strings. ------Language: It is designated by the client with the code of 8 Octet character strings to describe information returned from SMP. For example, information returned from SMP is in English if English is selected. Chinese and English are supported in current version.
IV. Session header (18 Bytes)

------Session ID: It is denoted by an integral (8 Byte) of 32 bits in hexadecimal format. ------Session control character: It is denoted by 6 Octet character strings (6 Byte). ------Reserved field: It is of 4 Byte used for subsequent extended services.
V. Transaction header (18 Bytes)

------Transaction ID: It is denoted by an integral (8 Byte) of 32 bits in hexadecimal format starting with 1. ------Transaction control character: It is denoted by 6 Octet character strings. ------Reserved field: It is of 4 Byte used for subsequent extended services.
VI. Operative information

It remains the same with that in version 1.00.
VII. Checksum (8 Bytes)

It remains the same with that in version 1.00.
2.2.3 Heartbeat Message

Start flag, message length and checksum of heartbeat message are identical with those of service message. HBHB is used to identify the heartbeat message. Heartbeat message is sent when no messages are transmitted within period C between SMP and BSS/OSS. And when N heartbeat messages are not received, the two is considered to be disconnected. Therefore, another login is required. Parameters C and N can be configured in principle. C = 2 minutes and N = 3 are recommended.
2.2.4 Timeout Judgment

SMP must return ACK message as the response of MML command sent from BSS/OSS within period T. When multiple ACK messages are involved, they must be sent with an interval of T until the transaction ends. SMP timeout occurs if BSS/OSS not receives the ACK message sent from SMP within period T. T can be configured in principle. T = 1 minute is recommended. However, T varies with transaction.
2.3 Format of a Message through the SMP Interface

Format of message through SMP interface is refer to Table 2-1. Table 2-1 Format of SMP message SMP processing Format of message (Downlink message: websmap->caa Uplink message: caa -> websmap ) Message start flag (4B) It is fixedly configured to 60 53 43 60 (that is, `SC`) Total length of the interval between message header and operative information. Fill with blank spaces based on practical situation. number It is used to identify the version of SMP open interface protocols It is used to identify the front end processor and terminal of BSS/OSS. It denotes the service that operators apply for. It is contained in version 1.01 and later ones. In current version, only Chinese and English are supported. With its value larger than 0, it is a unique identifier of the session originated by BSS/OSS. It varies with the session. By the use of session control character, BSS/OSS fills in DlgLgn, DlgCon respectively for login, message transmission and logout. When BSS/OSS send the logout message, SMP will return the Message filled with DlgEnd. It is used for subsequent extended services. It is allocated by the client (BSS/OSS) to identify a transaction. In the same session, they (value: larger than 0) are different from each other. TxBeg: Transaction start; TxCon: Transaction proceed; TxEnd: Transaction end It is used for subsequent extended services.
Message length (4B) Version (4B) Message header (20B in version 1.00, 28B in version 1.01 and later ones)
Terminal identifier (8B) Service (8B) name
Language (8B)
Session ID (8B)
Session header (18B)
Session control character (6B)
Reserved (4B) Transaction (8B) Transaction header (18B)
field
ID
Transaction control character (6B) Reserved (4B) field
SMP processing Format of message (Downlink message: websmap->caa Uplink message: caa -> websmap ) Operative information Operative information Blank space It denotes MML command. See Chapter 3 for details. Blank spaces are required, if the length of MML command is not the multiple of 4. Perform XOR for Message header + Session header + Transaction header + Operative information as 32 Byte.
Checksum
8B
2.4 MML Command Format

2.4.1 MML Command
A command is started with a command code that specifies its function implemented by the system. And further information is contained in parameter part following the command code. This part is separated from the command code with a colon and defined by the parameter block. Among multiple commands, semicolon is adopted, while it is omitted in one command. In addition, parameter part is always omitted.
Command code : Parameter block
Figure 2-1 Figure 1 Format of MML command
Note: Several commands are not listed.
2.4.2 Command Code

It consists of command prefix and body without match of upper/lower case. Command prefix denotes the type of command. A command with the prefix of ACK is an acknowledgement one, and the prefix is separated from the command body with a colon, while a command started with MON refers to a detection command. In addition,
the command is a notice message when NOTIFY is taken as the prefix. Prefix MON is not supported temporarily in current version. Command body is composed of 3 identifiers at most, which are separated with blanks.
Command prefix : Identifier 1 sp Identifier 2 sp Identifier 3
Figure 2-2 Format of command code Meaning: -Identifier 1: With a maximum length of 8 Byte, it denotes the operation to be executed. QRY, DISP, MOD, CRE. -Identifier 2: With a maximum length of 8 Byte, it denotes the service involving the operation. DGNK, VPN, IN800. -Identifier 3: With a maximum length of 8 Byte, it denotes the target of operations. ACNT, OPER. For example: Carry out the command DISP VPN ACNT : MSISDN="13900001234" to list the VPN account.
2.4.3 Parameter Block

Parameter block is indispensable to execution of the function specified by command code. And a command determines parameters contained in the block. Two or more parameters in one block are separated with commas. All parameters are defined based on their names, so execution of command may not be affected when user inputs them in a casual order.
I. Definition
A parameter consists of a name and a value, which are separated with =. If value of a parameter is omitted, the corresponding name, = and , (between parameters) must be omitted as well. A default value is designated when the parameter is omitted. However, the default value can be replaced with a specified parameter value.
II. Name
Parameter name is denoted by an identifier with up to 8 characters. Upper and lower cases are not matched for a parameter name.
III. Value
Parameter value refers to an information element or a combination of information elements.
IV. Information element

Identifier Decimal number Date Time Character string
Figure 2-3 Format of information element
V. Combined information elements

Several information elements can be input in a parameter contained in the command after they are combined into one. As mentioned above, only the combination of simple information elements is taken into account in this document. SMP open interface supports flexible combination modes of information elements. To count the number of them, separate information elements in the parameter value with &. For example, 5 & 9 denotes 5 and 9. Information elements of least and most significant bits as well as && (between the two) are required to denote a sequence (Incremental = 1) of information elements. For example, 5 & & 9 refers to 5, 6, 7, 8, and 9, while N'62280000 && N'62289999 denotes a number segment with 10,000 numbers.
Note: && is supported in part of MML commands.
Number of information elements involved in a combination is limited by the size of a message. In current version, the size is 65535 bytes.
VI. Default parameter

Parameters in a command can be divided into mandatory one, optional one and default one. Mandatory parameter: Indispensable to the execution of a command Optional parameter: Dispensable one in execution of a command Default parameter: It is configured by the system automatically. Pay attention to the following rules about the default parameter: 1. A parameter configured with default value must be designated to be default. (Non-critical parameters involved in a command to add a user can be configured with the default value.) 2. Default value of parameters in a command is unique. 3. A default parameter can be configured with different values in different commands. 4. Default value must be the one commonly configured for this parameter.
2.4.4 Character Set in MML Command

I. Letter
It includes letters from a to z in upper and lower case.
II. Digit
It includes all decimal digits as well as those from 0 to 9.
III. List separator

It is used to separate information elements in the conversation. (:): It is used to separate the command name or code from the first parameter. (=): It is used to separate the parameter name or code from the first value of the parameter. (,): It is used to separate parameters. &: It is used to separate equivalent characters in a parameter. &&: It is used to separate the upper and lower limit of an equivalent character. (): It is used to separate the value from its indicator.
(;): It is used to separate commands.
IV. Numerical system indicator

B: Binary O: Octal D: Decimal H: Hex N: Numerical character string
V. Special character
("): It is used to emphasize character strings in a text as a mnemonic. Blank: It is used to separate command codes as well as increase readability. Carriage return: It is unavailable in this system, but it can be used to increase readability. * # Chinese character (-)
2.5 MML Grammar

2.5.1 Identifier
Identifier refers to a character string containing one or more characters. Started with a letter or an underline, it includes numeral, /, letter and underline. For example, UPDATE and NO7.
Figure Letter/underline Letter/underline
Figure 2-4 Identifier format
2.5.2 Numerical Value

I. Decimal number
Decimal number is composed of D and a group of characters involving one or more figures. Numerical system is applied to information element, in which D can be omitted.
Figure D
Figure 2-5 Format of decimal number
II. Numerical character string

Numerical character string is used to denote such numerical information as card number or telephone number that decimal number fails to denote.
Figure
Figure 2-6 Format of numerical character string
III. Character string
Character(excluding)
"
Figure 2-7 Format of character string
"
Text and delimiter can be input in a character string (text string). The delimiter is of grammatical meaning when input beyond the text string. Text string is a string of characters with the number of 0 or more and contained between quotation marks. All characters even double quotation marks (\ must be input before it.) can be input in a text string.
IV. Date
The date is denoted by putting the date in digital format into the quotation mark. It conforms to the order of Year, Month, Day, among which Year is denoted by a decimal number of 4 digits, while Month and Day are denoted by a decimal number of 2 digits. Between the three, hyphens are put. For example: October 13 2003 must be "2003-10-13".
V. Time
The time is denoted by putting the time expressed with digit and colon into double quotation marks in the timing system of 24 hours. Time elements are ordered like that: Hour, Minute, Second, which are denoted by a decimal number of 2 digits. Among them, Hour is denoted by the number ranging from 00 to 23, while Minute and Second are from 00 to 59 (59 is included). For example: 25 minutes and 1 second past 12 can be denoted like that: "12:25:01".
VI. Date and time

Date and time are denoted based on formats mentioned above, between which there is a blank space. For example: 25 minutes and 1 second past 12 October 13 2003 can be denoted as below: 2003-10-13 12:25:01"
2.6 MML Features

2.6.1 Batch Operation
It indicates that only one command is executed to implement certain a process (such as adding, deletion, modification and query) for objects of the same kind. For example, subscription for multi-function card service. Functions of batch operation are listed as follows: 1. Progress feedback function must be supported. 2. A result must be output when a small batch operation is completed and a statistical result is output when all operations end. 3. Concurrent execution of batch command and common one must be allowed.
2.6.2 Confirmation Prompt

A prompt of confirmation must be displayed for users in case of important operations. For example, a timer is activated upon the execution of an important command so that execution may be cancelled when timeout occurs.
2.7 Interaction between BSS/OSS and SMP

2.7.1 Procedure
The complete procedure of interaction between BSS/OSS and SMP is illustrated in the figure below. For a brief description, handling of abnormal cases and establishment of multiple sessions are not involved.
BSS/OSS Establish a SOCKET connection Send a LOGIN message LOGIN success SMP IN
Send a MML message Send to IN Return a ACK message to SMP Send a MML ACK message
Send a LOGOUT message
LOGOUT success Release SOCKET connection
Figure 2-8 Interaction between SMP and BSS/OSS
2.7.2 Information Flow
Start
Establsh a SOCKET connection between BSS/OSS and SMP
Success or not Yes Send a login message
Operation starts
Whether SMP succeeds in returning a message
Send the first MML command
Yes TransactionID+1 No No
No
Concurrent operations
Execute the operation
Send all commands or not?
Receive MML ACK messages
No
No Whether operations are not required Yes Send the next MML command
Yes Transaction ends or not? Yes
Send a logout message
Wait for the end of all operations
Release SOCKETconnection Operatio n ends End
Figure 2-9 Procedure of Interaction between BSS/OSS and SMP
Note: Multiple sessions can be established concurrently based on one TCP connection. Each session starts with DlgLgn and ends with DlgEnd. Multiple transactions can be started concurrently in a session. Each transaction starts with TxBeg and ends with TxEnd. Each transaction can contain multiple messages. Only one MML or MML ACK command can be stored in the operative information field of a message.
Chapter 3 Commonly-Used MML Command Set

A piece of MML command is sent from MD to SMP, while the command with prefix ACK: is sent from SMP to MD.
3.1 Interface Description

3.1.1 Parameter Description
All the parameters of character string should be put in the double quotation marks.
I. Description of the usage of "&":

This symbol has special meaning in MML command: It represents one parameter corresponds to multiple values. For example: To create a subscriber: CREATE PPS MULTISUB: MSISDN=13500000&&13500500 (represents all the numbers from 13500000 to 13500500) CREATEPPS MULTISUB:MSISND=13500001&13800001 (It represents the two numbers of 13500001 and 13800001) To query the basic subscriber information: DISP PPS ACNTINFO: MSISDN=13500000, ATTR=BALANCE & SUBSPID & SUBCOSID (It represents querying the three fields including BALANCE, SUBSPID, and SUBCOSID respectively). No parameter is allowed to use this symbol except the description says so.
II. Description of the input parameter being an integer:

If the input parameter is larger than or equal to zero, it cannot include any symbols. For example: SUBCOS=2 (legal), PackageID=0 (legal), SUBCOS=+2 (illegal), PackageID=-0 (illegal), PackageID=+0 (illegal). If the input parameter is smaller than zero, then the input format is negative symbol plus a digit (no symbol can be input except the negative symbol). For example: DMFDINCREMENT=-100 (legal), DMFDINCREMENT=10-60 (illegal),
DMFDINCREMENT=-+60 (illegal)
3.1.2 Special Note

The universal returned information of parameters RETN and DESC in the ACK of MML command is as follows: 0: Succeeded 1: Illegal data packet 2: Session control word error 3: Transaction control word error 4: Syntax error or illegal command code 5: Session created 6: Access agent connecting to the system failed 7: System internal error 8: Parameter input error 9: Command code mismatched 10: Incorrect number of operations 11: Operation timeout 12: No authority to access the data 13: Operation authentication failure 14: SMP database operation failure 15: SCP execution error 16: SCP connection failure 17: SCP no response 18: Recharging system execution error 19: Recharging system connection failure 20: Recharging system no response 21: Querying SCP failed 22: Querying SDP failed 23: Mapping between MSISDN and SCP does not exist. 24: MSISDN does not in SCP.
25: Service name error 26: Message forwarding failure 27: System forcibly terminates the current session. 28: Operation code does not exist. 29: Max. subscriber license in the province has been reached. 30: Max. traffic in the province has been reached. 31: Max. subscriber license of the system has been reached. 32: Max. operation license of the system has been reached. 33: Terminal ID error 34: Client transaction ID error 35: Canceling transaction failed 36: Session ID error 37: File operation failure 38: IP connection failure 39: System overloaded, operation request is prohibited. 40: Service area is not allocated to the MSISDN or HLR does not exist.
3.2 Common Errors

On receipt of the operator command, if the input command has grammatical errors, or the message format is illegal, an error-indicating message will be returned. Output format: ACK: GENERAL ERROR: RETN = , DESC=
Output parameters: Parameter RETN DESC Error code Description of the error Description Value range
3.3 Service Center (EVC)

3.3.1 Logging in
It is used for the operator to log in to the SMS system. Input format: LOGIN: USER= , PSWD=
Input parameters: Parameter USER PSWD Description ID for operator login. Password for operator login. Value Range Represented by a character string of 1 through 8 digits. Represented by a character string of 1 through 8 digits.
3.3.2 ACK of Logging in

This prompt returns to receipt of the login command from the operator. Output format: ACK: LOGIN: RETN= , DESC=
Output parameters: Parameter RETN Description Returned value of the ACK command. Value range Decimal integer.
Parameter
Description
Value range A string of no more than 256 characters. 0: Success. 1001: Operator does not exist. 1002: Password is not correct. 1003: Operator login ID has expired. 1004: Operator password has expired.
DESC
Description on returned value.
the
1005: Invalid operator state 1006: The operator is denied at the present time. 1007: Terminal ID does not exist. 1008: The terminal is denied to access at present. 1009: The max login failure times are reached. 1010: Login authentication failed.
3.3.3 Logging out

End the conversation between the operator and the SMS system. Input format: LOGOUT :[ USER=]
Input parameters: Parameter Description The login ID for the operator who wants to exit. USER Only when the login of other operators is to be cleared, is this parameter necessary. Value range Represented by a character string of 1 through 8 digits. DEFAULT The login ID of the operator in the current conversation.
3.3.4 ACK of Logging out

This prompt returns on receipt of the command of logging out. Output format: ACK: LOGOUT: RETN= , DESC=
Output parameters: Parameter RETN Description Returned value of the ACK command. Value Range In decimal integer A string of no more than 256 characters. 0: Success. Description on returned value. the 1001: The current operator is not authorized to log this operator off. 1002: The specified operator has not logged in. 1003: The specified operator does not exist.
DESC
3.4 EVC Service

3.4.1 Modifying AD Stock
Function description: This command enables a system operator to modify the stock of an AD through an MML command. Input format: MODI EVC STOCK:HPNO=,EVTYPE=,PRICETYPE=,INCREMENT=
Input parameters: Parameter HPNO Description Indicates a hand phone number, compulsory. It is a numerical character string of up to 24 digits. It cannot be null. Indicates a brand type, compulsory. It is a character string of up to 10 digits. It cannot be null. (1-simPATI ; 2-kartu AS) Indicates a price value, compulsory. It is a character string of up to 12 digits. It cannot be null. PRICETYPE (when EVTYPE=1, the value can be 20, 50, 100 and 150; when EVTYPE=2, the value can be 15, 20, 25, 50 and 100) INCREMENT Indicates a stock to be added, compulsory. It is a positive integer.
EVTYPE
Example: MODI EVC STOCK:HPNO=811123456,EVTYPE=1,PRICETYPE=20,INCREMENT= 100
3.4.2 ACK of Modifying AD Stock

Output format: ACK: MODI EVC STOCK:RETN=,DESC=
Output parameters: Parameter RETN DESC 10101 10102 10103 10104 10105 Description Indicates a returned value of the ACK command. It is a positive integer or the value 0. Indicates the returned description. It is a character string of up to 256 digits. The entered stock exceeds the limit specified by the system. The service is not loaded. The entered AD does not exist or it is not an AD. The modified stock exceeds the limit specified by the system. The entered brand type or price type does not exist.
3.4.3 Suspending an RS
Function description: This command enables a system operator to suspend an RS. Output format: SUSPEND EVC RS: HPNO=,OPRTYPE=
Output parameters: Parameter HPNO Description Indicates a hand phone number, compulsory. It is a numerical character string of up to 24 digits. It cannot be null. Indicates an operation type, compulsory. It is a numerical character of one digit. The value 1 means suspending an RS. It cannot be null.
OPRTYPE
Example: SUSPEND EVC RS: HPNO=811123456, OPRTYPE=1
3.4.4 ACK of Suspending an RS

Output format: ACK: SUSPEND EVC RS:RETN=,DESC=
Output parameters: Parameter RETN DESC 10201 10202 10203 Description Indicates a returned value of the ACK command. It is a positive integer or the value 0. Indicates the returned description. It is a character string of up to 256 digits. This hand phone number does not exist. This hand phone number cannot be suspended. This SCP number does not exist.
3.4.5 Adding an RS
Function description: This command enables a system operator to add a RS. Input format: ADD EVC RS:ADHPNO=[,SDHPNO=],RSHPNO=,ICCID=,PWD=,CFMPWD=, DLNAME=[,CONTACTMM=][,EMAIL=][,ADDRESS1=][,ADDRESS2=][,POSTALC ODE=][,CITY=][,PHONENO=][,FAXNO=]
Input parameters: Parameter ADHPNO Description Indicates a hand phone number of an upstream AD, compulsory. It is a numerical character string of up to 24 digits. It cannot be null. Indicates a hand phone number of an upstream SD, optional. It is a numerical character string of up to 24 digits. It cannot be null. If you do not enter it, a direct AD downstream channel is added. Indicates an RS hand phone number to be added, compulsory. It is a numerical character string of up to 24 digits. It cannot be null. This item is compulsory. It is a character string of up to 20 digits. It cannot be null. Indicates a PIN of a dealer, compulsory. It is a numerical character string of four to eight digits. It cannot be null. Indicates a confirmation PIN of a dealer, compulsory. It is a numerical character string of four to eight digits. It cannot be null. Indicates a dealers name, compulsory. It is a character string of up to 60 digits. It cannot be null. Indicates a dealer's contact mother's maiden name, optional. It is a character string of up to 60 digits. It cannot be null. Indicates an Email address, optional. It is a character string of up to 80 digits. It cannot be null. Indicates address 1, optional. It is a character string of up to 60 digits. It cannot be null. Indicates address 2, optional. It is a character string of up to 60 digits. It cannot be null. Indicates a Postal code, optional. It is a numerical character string of up to 10 digits. It cannot be null.
SDHPNO
RSHPNO
ICCID PWD
CFMPWD
DLNAME
CONTACTMM
EMAIL ADDRESS1 ADDRESS2 POSTALCODE
Parameter CITY PHONENO FAXNO
Description Indicates a city, optional. It is a character string of up to 60 digits. It cannot be null. Indicates a phone number, optional. It is a numerical character string of up to 24 digits. It cannot be null. Indicates a fax number, optional. It is a numerical character string of up to 24 digits. It cannot be null.
Example1: ADD EVC RS:ADHPNO=811123456,RSHPNO=811155555,ICCID=101010,PWD= 123456,CFMPWD=123456,DLNAME=PANDY Example2: ADD EVC RS:ADHPNO=811123456 ,SDHPNO=81199999,RSHPNO=811166666, ICCID=101010, PWD=123456,CFMPWD=123456,DLNAME=TGHH,CONTACTMM= SANDA,EMAIL=pandy@telkomsel.com,ADDRESS1=XiYaTuRoad,ADDRESS2=XiY aTu2 Road,POSTALCODE=58001,CITY=Djakarta,PHONENO=88888888,FAXNO=80008 000
3.4.6 ACK of Adding an RS

Output format: ACK:ADD EVC RS:RETN=,DESC=
Output parameters: Parameter RETN DESC 10301 10302 10303 10304 Description Indicates a returned value of the ACK command. It is a positive integer or the value 0. Indicates the returned description. It is a character string of up to 256 digits. The service is not loaded. An RS exists or it exists as an AD or SD. The entered AD does not exist or it is not an AD. The entered AD is in the status that an RS cannot be added.
Parameter 10305 10306 10307 10308 10309 10310 10311 10312
Description The entered AD or SD does not exist or the level is inconsistent. The entered AD or SD is in the status that an RS cannot be added. The entered AD and SD have no upstream/downstream relationship. No corresponding number segment exists in this region. There is such data limiting the number of RSs of the dealer in the system. RSs of the dealer exceed the limit specified by the system. The corresponding region does not exist. The number of RSs in this region exceeds the limit.
Acronyms and Abbreviations

A
AD Authorized Dealer
B
BOSS Business Operation Support System
C
CHANNEL Customer CHANNEL Telkomsel Prepaid User
D
DP Disconnect-Pending
E
EVOUCHER Electron Voucher
F
FN Familiarity Number
G
GSM GW Global System for Mobile Communication Gateway
H
HLR Home Location Register
M
MD MML MSISDN Medial Device Man-Machine Language Mobile Station International ISDN Number
P
PPS Pre-paid Service
R
REGAE RS Recharge Gateway Re-Seller
S
SCP Service Control Point
Huawei Technologies Proprietary A-1
SD SM SMAP SMOI SMP
Sub Dealer Service Management Service Management Access Point Service Management Open Interface Service Management Point
T
Telkomsel Telkomsel
V
VC VIP VOMS Voucher Center Very Important Person Voucher Management System
Huawei Technologies Proprietary A-2

01-EVC SMOI User Manual Body

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

01-EVC SMOI User Manual Body

Uploaded by

Copyright:

Available Formats

User Manual EVC Service Management Open Interface

User Manual EVC Service Management Open Interface

Huawei Technologies Proprietary ii

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

Chapter 1 SMOI Protocol

1.2 Networking Mode of SMP

MD:SMOI /Local Server

MD:SMOI /WEB SERVER

MD:SMOI /Bank Interface

Business Hall Terminal

Huawei Technologies Proprietary 1-1

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

1.3 Architecture of SM Interface

SMP SM Interface protocol layer TCP/IP Physical layer

MD SMOI SM Interface protocol layer TCP/IP Physical layer

1.4 Program of SM Interface

Huawei Technologies Proprietary 1-2

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

1.5 MML Commands

Figure 1-3 Format of MML command

II. Command code

Huawei Technologies Proprietary 1-3

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

III. Parameter block

Huawei Technologies Proprietary 1-4

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

1.5.2 Character Set for MML Commands

IV. Number scale

Huawei Technologies Proprietary 1-6

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

1.5.3 MML Syntax

Figure 1-6 Identifier

Huawei Technologies Proprietary 1-7

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

Figure 1-9 Character string

V. Date and time

Huawei Technologies Proprietary 1-8

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

Establish SOCKET connection with SMP

Send LOGOUT command

Figure 1-10 Procedure of the interaction of MD with SMP

1.6 Standard Interface Software

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

Huawei Technologies Proprietary 1-10

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

1.6.2 Relationship between Standard Interface Software

1.7 Security Management of SMP

1.7.2 Access Security

Huawei Technologies Proprietary 1-11

User Manual EVC Service Management Open Interface

Chapter 1 SMOI Protocol

1.7.3 Operation Security