☰
Navigation :

PI-C Messages

Introduction

The PI-… messages are used to send a PI client request to an NCC Provisioning Interface server. The NCC PI supports two different transport mechanisms:

Both of these can be accessed from n2svcd by using PI-C-REQUEST in conjunction with the relevant client applications.

Note that you can also use SOAP-C-REQUEST to invoke a PI client request via the SoapClientApp. The PI-C-REQUEST is a simpler message which supports on the basic subset of the SOAP-C-REQUEST message content. The sole advantage of using PI-C-REQUEST over SOAP-C-REQUEST is that it is compatible with both MmlClientApp and SoapClientApp and so you can easily swap between MML and SOAP.

The following applications from the core n2svcd module make requests to SoapClientApp.

The internal PI-… messages are:

Note that this page uses the term “on-the-wire” to refer to the sending or receiving of SOAP or MML content. This term is also inclusive of the case where the message is sent by local loopback and does not physically transit a Network Interface Controller (NIC).

PI-C-REQUEST

The PI-C-REQUEST message is sent to MmlClientApp or SoapClientApp by any application that wishes to perform an outbound PI request using the MML or SOAP transport.

Refer to the SoapClientApp Configuration or the MmlClientApp Configuration documentation for more information on setting default parameters.

The attributes of the PI-C-REQUEST message are:

Field Type Description
pi Object Container for the parameters of the PI request that we are to send.
.command String [Required] The PI command to execute, e.g. NPYZ1=ADD.
.parameters Object [Required] A HASH of parameters to be passed in the request.
Each Object attribute is a named parameter which must be either a non-null SCALAR or an ARRAY of non-null SCALARs (for repeated parameter values).

Note that it is not possible to set or override connection or SSL parameters in the PI-C-REQUEST message. Connection and SSL parameters can only be set in the SoapClientApp configuration.

PI-C-SENT

The PI-C-SENT message is sent by SoapClientApp to the requesting application when the original PI-C-REQUEST is placed on-the-wire.

The attributes of the PI-C-SENT message are:

Field Type Description
pi Object The PI parameters used to encode the final on-the-wire PI request.
This Object has the same structure as the rest Object in PI-C-REQUEST.
Note however that this object will also contain any field values which were filled-in using default values configured within MmlClientApp or SoapClientApp itself.
mml String The full content of the on-the-wire MML Request when the message is sent via MML.
http String The full content of the on-the-wire HTTP Request when the message is sent via SOAP.

PI-C-RESPONSE

The PI-C-RESPONSE message is sent by SoapClientApp or MmlClientApp to the requesting application when a SOAP or MML response is received to the original PI-C-REQUEST, or if a failure occurs which indicates that no such Response will be received.

The attributes of the PI-C-RESPONSE message are:

Field Type Description
success 0/1 [Required] Indicates if the request was successful or not.
error String Indicates the reason why the request failed.
Present and applicable only if success == 0.
pi Object Container for the PI response parameters received.
Present only if success == 1.
.status ACK/NACK Was this a successful PI request or not.
.returned Object The returned parameters in the case of ACK status.
A HASH of returned parameters, keyed by parameter name.
The value will be a SCALAR if the parameter occurred only once.
The value will be an ARRAY of SCALAR if the parameter occurred more than once.
.info String A fault reason in the case of NACK status.
http String The full HTTP Response message when using SOAP. This field may or may not be present.
The SoapClientApp may decide not to supply it in order to reduce traffic on the message bus.

Note that the error field will be set in the case of a timeout or protocol-level encoding/decoding error. The pi.info field will be set in the case where the request is successfully transmitted but is declined by the NCC PI server.