Web Service Delivery 2.0

Introduction

The current web applications are no longer enough. The present Electronic business does not integrate the Internet applications with the rest of the companies’ software. If the companies want to get the maximum benefit from the Internet, websites must evolve. This is the context in which web services emerge.

That is the reason why the concept of web services has strongly come up in the last years, and it was even confirmed that it would change the way of programming the Internet-oriented applications to a service-oriented architecture. We could say that a web service is an application that can be descripted, published, localized and invoked through a network, generally the Internet. It combines the best aspects of the development based on components and the Web. Like the components, the web services are functions that are inside a black box, that can be reused without worrying about how they were implemented. Unlike the current technology of components, instead of being accessed through specific protocols of objects’ model, like RMI, DCOM or IIOP; they are accessed by using web protocols, like HTTP and XML. The web services’ interface is defined in terms of the messages it accepts and returns, therefore the web services consumers can be implemented in any platform and in any programming language, it just has to be able to create and consume the messages defined by the web services’ interface.

The Web Services’ Model

The basic architecture of the web services’ model describes a consumer, a supplier (the one implements) and occasionally a broker (broker UDDI). The publishing, finding and connecting operations are related to these agents. The basic idea is that a supplier publishes their services to a broker, then a consumer connects to the broker to find the required services and once this is done, a connection between the consumer and supplier is made. Each entity can play one or all of the roles.

For all the above, there are certain requirements when developing or consuming the web services:

A standard way of representing the data.

XML is the obvious option for this requirement.

A common and extensible message format.

SOAP is the chosen one in this case; SOAP is a lightweight protocol for information exchange. We will see this in more detail later on this document.

A common and extensible language to describe the services.

In this case the option is WSDL. It is a language based on XML and developed by IBM and Microsoft.

A way of discovering Internet’s services.

UDDI is used for this purpose; it specifies a system to publish and localize the services of the suppliers and consumers, respectively. We will see this in more detail later on this document.

Web Oca Delivery 2.0 Service Description

OCA’s Service’s Description is available through the methods of the WebServices SigmaService and they are published in the following URL :

http://www1.oca.com.ar/SigmaWebService/SigmaService.asmx.

The Public Methods of this Web Services are:

EstadoMotivoActualXML

This method is used to check the status and motive of the current processing of an item.

It has 9 parameters: clienteLogueo (client’s Loguin), usuario (username), password, clienteConsulta (client’s enquiry), producto (product), numeroPieza (item’s number), IdpiezaOca (OCA’s Item’s Id), Operativa (Operations), mostrarDatosAdicionales (show additional data)

These have a comma which delimitates the parameters (for example, “CCC,CCC25501,XXXXXX,CCC,,1080661,,,”; where:

ClienteLogueo = the client’s acronym registered at OCA’s business operation, in the example: CCC (We will later inform them which one corresponds to them).
Usuario = the client’s username code, in the example: CCC25501 (We will later inform it to them).
Password = the client’s username’s password (We will later inform it to them).
Clienteconsulta = They have to place the client’s acronym again, in the example: CCC (We will later inform it to them).
Producto = It’s the product’s established code, e.g. “108410” (Optional)
NumeroPieza = The item’s tracking number that is required to be checked.
IdPiezaOca = OCA’s unique identifier for the items to be distributed. (Optional)
Operativa = The business operations code of the service, e.g. “108410” for passports. (Optional)
MostrarDatosAdicionales = Empty.

It returns the following:

NumeroPieza = Number of the item to be tracked.
EstadoMotivo = Status/Motive of the current processing of the item.
FechaEstado = Date/Time of the current Status/Motive of the item.
Operativa = Description of the service’s operation.
Recibo = The receipt number used to pick up the items.
Carta = Number of the Statement Letter
Cliente = Client’s description.
Subservicio = OCA’s Subservice Code.
SucursalOCA = Acronym and description of the current OCA’s branch store where the item is located.
SucursalCliente = Client’s branch store’s code.
IdpiezaOca = Unique Identifier of the OCA’s item.
Destinatario = Last name and first name of the item’s addressee.
TipoPieza = Item’s type, e.g. Standard Item, Additional Item, Packages, etc.
FechaInclusion = Date/Time of the item’s logical file inclusion in case the item has a logical file, otherwise it remains empty.
FechaEnvio = Date/Time of the moment the client sent OCA the file (Header’s Date-Time) if it came with a logical file; otherwise it remains empty.
PlanillaEnvio = The Item’s Shipment Form Number.
FechaPlanillaEnvio = Date/Time the Shipment Form was sent to OCA’s branch stores.
FechaRendicion = Date/Time of the item’s issue.

In XML format, informing as the Dataset headline the word “Id” + the IdPieza of OCA. An example of how this XML would be generated is attached, which can be displayed dynamically on any Java or .NET form, as an example, see figure 1 where you can see how the XML is generated and how it would appear on an Explorer page’s grid.

        
          
        < OCAServiciosDLV2_0 >
            < ID11211446 >
              < NumeroPieza > 1080661 < /NumeroPieza >
              < EstadoMotivo >Rendida al Cliente: Entregada < /EstadoMotivo >
              < FechaEstado >30/08/2010 12:00:00 a.m. < /FechaEstado >
              < Operativa > 108410-Distribucion de Sobres – CCC < /Operativa >
              < Recibo >4843685 < /Recibo >
              < Carta >181121 < /Carta >
              < Cliente > CCC – Cliente de OCA < /Cliente >
              < Subservicio >SS < /Subservicio >
              < SucursalOCA >FLS (FLORES) < /SucursalOCA >
              < SucursalCliente >0000000002 < /SucursalCliente >
              < IdPieza >11211446 < /IdPieza >
              < Destinatario />
              < TipoPieza > Pieza Normal < /TipoPieza >
              < FechaInclusion />
              < FechaEnvio />
              < FechaPlanillaEnvio >11/08/2010 - 03:54:57 p.m. < /FechaPlanillaEnvio >
              < FechaRendicion >19/08/2010 12:26:42 a.m. < /FechaRendicion >
            < /ID11211446 >
          < /OCAServiciosDLV2_0 >

HistoricoSeguimientoXML

This method returns the history of all the methods/motives of an item in XML format.

It has 8 Input parameters: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa

These have a comma which delimitates the parameters (for example, “CCC,CCC25501,XXXXXX,CCC,,1080661,,”; and where:

ClienteLogueo = the client’s acronym, in the example: CCC (We will later inform them which one corresponds to them).
Usuario = the client’s username code, in the example: CCC25501 (We will later inform it to them).
Password = the client’s username’s password (We will later inform it to them).
Clienteconsulta = They have to place the client’s acronym again, in the example: CCC (We will later inform it to them).
Producto = It’s the product’s code, e.g. “VISA”. (Optional)
NumeroPieza = The item’s tracking number.
IdPiezaOca = OCA’s unique identifier for the items to be distributed. (Optional)
Operativa = The operation code of the service (Optional)

It returns the following:

FechaEstadoSolicitud = Date/Time of the Item’s Status.
EstadoDescripción = Description or Status or Action of the Item.
MotivoDescripción = Item’s motive description.
Usuario = Description of the user who took part in that status/motive.
FechaEjecución = Date/Time of the action’s execution, it is only valid when the action’s status is Executed, Cancelled or Rejected.
Respuesta= It’s the action’s result’s description. It can be successfully executed, rejected, cancelled or entered.
Motivo = If the action is rejected, it is valid and it indicates the reason why the action was rejected.

          
            
  < OCAServiciosDLV2_0 >
    < ID11211446 >
      < FechaEstadoSolicitud>11/08/2010 11:44:28 a.m.< /FechaEstadoSolicitud >
      < EstadoDescripcion>Lógico Recibido< /EstadoDescripcion >
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion >
      < Usuario>Usuario para inclusión. 9W1, SISTEMAS(SISTEMAS)< /Usuario >
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < /ID11211446>
      < FechaEstadoSolicitud>11/08/2010 11:56:16 a.m.< /FechaEstadoSolicitud >
      < EstadoDescripcion>Fisico Recibido< /EstadoDescripcion >
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion >
      < Usuario>Gimenez, Pablo(101606)< /Usuario >
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
      < ID11211446>
      < FechaEstadoSolicitud>11/08/2010 11:57:03 a.m.< /FechaEstadoSolicitud >
      < EstadoDescripcion>A Enviar a Sucursal Oca< /EstadoDescripcion >
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion >
      < Usuario>Gimenez, Pablo(101606)< /Usuario >
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446 >
    < ID11211446 >
      < FechaEstadoSolicitud>11/08/2010 03:54:54 p.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Despachada a Sucursal Oca< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Alonso, Javier(103083)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>12/08/2010 06:13:01 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Recepcionada en Sucursal< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>12/08/2010 03:39:01 p.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>En Distribución< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>14/08/2010 08:11:01 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>En Calle< /EstadoDescripcion>
      < MotivoDescripcion>Sin Motivo< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>14/08/2010 04:55:02 p.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Despachada a Planta Impositora< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>10/09/2010 11:47:26 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Reenviar< /EstadoDescripcion>
      < MotivoDescripcion />
      < Usuario>romar, lorena(23)< /Usuario>
      < FechaEjecucion>15/09/2010 01:13:33 p.m.< /FechaEjecucion>
      < Respuesta>Ejecutada con éxito< /Respuesta>
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>18/08/2010 10:01:18 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>A Generar Carta de Rendición< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>RAMIREZ OCSA REMBERTO, ANDRES(101612)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
    < /ID11211446>
    < ID11211446>
      < FechaEstadoSolicitud>19/08/2010 12:31:03 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Pendiente de Habilitar Carta Para Envio< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>Cabrera, Natalia(79225)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
      < ID11211446>
      < FechaEstadoSolicitud>25/08/2010 07:50:22 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Rendición enviada al Cliente< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>RODRIGUEZ , JUAN DIEGO(78611)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
      < ID11211446>
      < FechaEstadoSolicitud>30/08/2010 12:00:01 a.m.< /FechaEstadoSolicitud>
      < EstadoDescripcion>Rendida al Cliente< /EstadoDescripcion>
      < MotivoDescripcion>No Existe Numero< /MotivoDescripcion>
      < Usuario>Sistema, Usuario(sistema)< /Usuario>
      < FechaEjecucion />
      < Respuesta />
      < Motivo />
      < /ID11211446>
  < / OCAServiciosDLV2_0>

EjecutarAccionXML

This method is used to enter actions to an item that is in the system; the user must have a profile set up for that action and the status/motive of the item must allow to enter the corresponding action.

It has 11 Input parameters: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa, idAccion, delimitador, filler

Where:

ClienteLogueo = the client’s acronym, in the example: CCC (We will later inform them which one corresponds to them).
Usuario = the client’s username code, in the example: CCC25501 (We will later inform it to them).
Password = the client’s username’s password (We will later inform it to them).
Clienteconsulta = They have to place the client’s acronym again, in the example: CCC (We will later inform it to them).
Producto = It’s the product’s code, e.g. “VISA”. (Optional)
NumeroPieza = The item’s tracking number that is required to be operated.
IdPiezaOca = OCA’s unique identifier for the items to be distributed. (Optional)
Operativa = The service’s operation code (Optional)
IdAccion = The Action code that is required to be executed.
Delimitador = Indicates the delimitator that is going to be used to transfer the data that are specified in the filler where the additional data of each action is indicated, e.g.: ; (semicolon)
Filler = They are indicated separated by the delimitator of the previous parameter, the data of each action, e.g. for an action of “Recovery at Branch Store”, it has to be specified using the semicolon as the delimitator, for example, 18;Devolver Urgente (18; Return Urgently), which would a Recovery at Branch Store action and the code number would be 18.

For instance, for an item to which an action of Recovery at Central Office (Action 19) is executed, the parameters would be the following:

CCC, CCC25501,Clavex,CCC,,2008060400303380,,,19,;,Devolver Urgente

And it would return the following:

                  
                  < OCAServiciosDLV2_0 > 
                    < ID27007 >
                      < ResultadoIngresoAccion >Acción Ingresada exitosamente – 21/09/2010 18:02:09
                      < /ResultadoIngresoAccion >
                    < /ID27007 >
                  < /OCAServiciosDLV2_0 >

If an error is generated due to an error in the parameters or to functional errors, for example, that an action cannot be yet entered to an item, the Web Services will report it through a message of exception, such as SoapException, so that if this exception message is caught, they will receive the corresponding error message, e.g. The action cannot be entered, the item has pending actions

AccionPendienteXML

This method returns the pending action of an item in XML format.

I has Input Parameters: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa.

Where:

ClienteLogueo = the client’s acronym, in the example: CCC (We will later inform them which one corresponds to them).
Usuario = the client’s username code, in the example: CCC25501 (We will later inform it to them).
Password = the client’s username’s password (We will later inform it to them).
Clienteconsulta = They have to place the client’s acronym once again, in the example: CCC (We will later inform it to them).
Producto = It’s the product’s code, e.g. “VISA”. (Optional)
NumeroPieza = The item’s tracking number.
IdPiezaOca = OCA’s unique identifier for the items to be distributed. (Optional)
Operativa = The service’s operation code (Optional)

It returns the following:

IdpiezaOca = OCA’s unique identifier.
DescripcionAccion = The description of the Action, e.g. Reschedule
FechaSolicitud = Date when the Action was requested.
UsuarioSolicitud = The user that requested the action.
Estado = The Action’s Status, it can be:
- Entered: When the client enters the action, this is its first status.
- Pending:
  - If the item is at the OCA’s branch store and it executes this action, it means it has to be returned to the Central Plant so that it is finally executed. The items remains in “Pending” status
- Executed: This status indicates that the action was successfully executed
- Cancelled: This is the action’s status when the client executes a Cancel Action.
- Rejected: If when executing the action, the status/motive of the item does not allow to execute the action because, for instance, the item has been delivered, the action is rejected.

For example:

                  < OCAServiciosDLV2_0 >
                    < ID6166816 >
                    < DescripcionAccion>Reenviar< /DescripcionAccion >
                    < FechaSolicitud>02/09/2010 11:48:20 a.m.< /FechaSolicitud >
                    < UsuarioSolicitud>romar, lorena< /UsuarioSolicitud >
                    < Estado>Ingresada< /Estado>
                    < /ID6166816>
                  < /OCAServiciosDLV2_0>

AccionesIngresadasXML

This method returns the history of all the actions entered of an item in XML format.

It has 8 Input parameters: clienteLogueo, usuario, password, clienteConsulta, producto, numeroPieza, IdpiezaOca, Operativa

Where:

ClienteLogueo = the client’s acronym, in the example: CCC (We will later inform them which one corresponds to them).
Usuario = the client’s username code, in the example: CCC25501 (We will later inform it to them).
Password = the client’s username’s password (We will later inform it to them).
Clienteconsulta = They have to place the client’s acronym again, in the example: CCC (We will later inform it to them).
Producto = It’s the product’s code, e.g. “VISA”. (Optional)
NumeroPieza = The item’s tracking number.
IdPiezaOca = OCA’s unique identifier for the items to be distributed. (Optional)
Operativa = The service’s operation code (Optional)

It returns the following:

IdpiezaOca
DescripcionAccion = The description of the Action, e.g. Reschedule
FechaSolicitud = Date when the Action was requested.
UsuarioSolicitud = The user that requested the action.
Estado = The action’s status, it can be:
- Entered: When the client enters the action, this is its first status.
- Pending:
  - If the item is at the OCA’s branch store and it executes this action, it means it has to be returned to the Central Plant so that it is finally executed. The items remains in “Pending” status.
- Executed: This status indicates that the action was successfully executed.
- Cancelled: This is the action’s status when the client executes a Cancel Action.
- Rejected: If when executing the action, the status/motive of the item does not allow to execute the action because, for instance, the item has been delivered, the action is rejected.
FechaEjecución = Action execution date, it is only valid when the action’s status is Executed, Cancelled or Rejected.
UsuarioEjecución = It is the user that requested the action, it is only valid when the action’s status is Executed, Cancelled or Rejected.

For instance, for an item with two actions executed, the IDpieza (item’s ID) is shown in 2 opportunities, one for each concurrence.
It is attached:

                  < OCAServiciosDLV2_0>
                    < ID11142128>
                    < DescripcionAccion>Reenviar< /DescripcionAccion>
                    < FechaSolicitud>27/08/2010 03:42:57 p.m.< /FechaSolicitud>
                    < UsuarioSolicitud>Giambeluca, Leonardo< /UsuarioSolicitud>
                    < Estado>Ejecutada< /Estado>
                    < FechaEjecucion>31/08/2010 09:37:27 a.m.< /FechaEjecucion>
                    < UsuarioEjecucion>gajardo, javier< /UsuarioEjecucion>
                    < /ID11142128>
                    < ID11142128>
                    < DescripcionAccion>Reenviar< /DescripcionAccion>
                    < FechaSolicitud>08/09/2010 10:25:05 a.m.< /FechaSolicitud>
                    < UsuarioSolicitud>Giambeluca, Leonardo< /UsuarioSolicitud>
                    < Estado>Ingresada< /Estado>
                    < /ID11142128>
                  < /OCAServiciosDLV2_0>

Credentials

To get the credentials and access to the webservices, you should get in contact with our IT area. You can make the request to the following e-mail address: integraciones@oca.com.ar