Addressing Service (Communication Channels)

Content

Addressing Service (Communication Channels)

An important part of the Integration Platform for PCS is surely the addressing service. Using this service, Integration Platform is able to notify the national systems that participate in the process. Railway Undertaking (RU) agencies are notified about each change of the dossier where they are participating during the “Harmonization” phase. Infrastructure Manager (IM) agencies are notified after each update of the particular dossier (where the agency is participating) in “Path Elaboration” phase. Additionally, the Integration Platform always notifies the leading IM agency when a dossier is switched to Path Request phase by the corresponding leading RU.

In order to execute the notification, Integration Platform needs to know the preferred communication channel for the particular national system. The organizations that want to test Integration platform are advised to specify the communication channel. 

Integration platform is able to communicate with other systems using following communication channels:

  • File System of the Integration Platform Server: the updated dossiers are saved to a directory on the server, the particular agency takes the document via FTP. For this purpose, the organization has to announce the outgoing IP address; RNE provides user credentials for FTP access.
  • FTP: the organization specifies FTP server address and user credentials for communication; RNE configures Integration Platform to upload the corresponding dossiers to the given FTP server
  • Web Service: the organization specifies HTTP server address and user credentials for communication; RNE configures Integration Platform to call the corresponding Web Services with content filled with dossiers. See the subchapter “Usage of web Service Notification” for details
  • E-Mail: the organization specifies e-mail address for communication; RNE configures Integration Platform to send the corresponding dossiers to the given e-mail address.

Constraint

There can only be one communication channel per agency defined.

Change set codes

Change set codes represent an extension of the change sets mechanism. Change sets mechanism show all the changes done between current and the last version of the dossier. Changes are grouped in change sets by the dossier segment that was changed.

Change set codes contains enough information for clients to check if they are interested to process the current notification or not.

Categorization

At the moment we have following change categories in which our clients are interested:

  1. Dossier state transition
  2. Path indicator change
  3. Dossier type change
  4. Processing status change for dossiers with path that contains PaP sections (dossier with PaP requests)
  5. Leading IM change
  6. New observation added

Changes that do not belong in neither of these categories are added in separate group:

  1. General

In future, if need arise, for changes from the general group we can separate them and add these changes into new group.

Format

Prerequisite

Our primary goal is to provide easy way for integrators to process only the notification messages for which they are interested. This means that the codes should be easy to interpret programmatically (e.g. regular expression) and to decide if notification message is important for them.

Additionally we want to achieve readable format which would be easy to understand and easy for troubleshooting.

Format details

In order to satisfy these needs we created the following format:

C,AI/P,S-T

C = change category.  This value represents one of the change categories. Possible values are:

  • DossierStateTransition,
  • PathIndicatorChange,
  • DossierTypeChange,
  • PathWithPaPProcessingStatusChange
  • LeadingIMChange
  • NewObservation
  • General.

A = agency type id for the agency that made the change. Possible values can be retrieved with web service operation getAgencyTypes.

I = agency id for the agency that made the change. All agencies can be retrieved using the getAllAgencies web service operation.

P = current RU IM pair. This is an optional part of the code used for partially harmonized dossiers. This information represents the RU IM pair which was affected by the change. The format is:

            RUIMPairID

            where ID is the id of the current RU IM pair.

S = source state

T = target state

Different change categories have different state representation:

  • Dossier state transition. One dossier state is represented as combination of process type and dossier status in following format:

P/S

P = process type. Valid values can be retrieved using the getSupportedDossierProcessTypesMatrix web service operation.

S = dossier status. Valid values can be retrieved using the getDossierProcessPhases web service operation.

  • Path indicator change. Source and target path indicator states are represented by a path indicator id. Valid values can be retrieved using the getAllProgressStatuses web service operation.
  • Dossier type change. Source and target dossier types are represented by a dossier type id. Valid values can be retrieved using the getSupportedDossierProcessTypesMatrix web service operation.
  • Processing status change for path with PaP. Valid values for source and target states are:
    • ProcessingByCoss for the case when C-OSS is working on the path
    • FOProcessingByIM when C-OSS requested a F/O from IMs
    • TailorMadeProcessingByIM when C-OSS requested a tailor made offer from IMs
  • Leading IM change. Source and target are represented by id of the previous and current leading IM.
  • New observation change. Source state is empty in this case. Target state is represented by id of the respective noteleement id.
  • General. State representation is omitted for this category.

Examples

Some change set codes:

  • DossierStateTransition,EVU5,N/D-N/C

User from RU (EVU) agency with id 5 promoted the “New process type” dossier from Open (D) to Harmonization (C)

  • DossierStateTransition,EVU5,N/C-L/E

User from RU (EVU) agency with id 5 promoted the “New path request” dossier from Harmonization to Path Request. During promotion process type was changed to “Late path request”.

  • DossierStateTransition,KM4,L/E-L/T

User from IM (KM) agency with id 4 promoted the “Late process type” (L) dossier from Path Request to Path Elaboration

  • PathIndicatorChange,EVU5,P-A

User from RU agency with id 5 change the path indicator from “Being processed” (P) to “Accepted” (A)

  • DossierTypeChange,EVU5,D-E

User from RU agency with id 5 changed the dossier type from Default to Path Cancellation

  • DossierStateTransition,EVU5/RUIMPairID5426,H/C-A/C

User from RU agency with id 5, RU IM pair id 5426, switched the dossier from Ad-Hoc Path Request to Ad-Hoc Partially Harmonized

  • LeadingIMChange,KM23,23-4

User from IM (KM) agency with id 23 changed leading IM from agency with id 23 to agency with id 4

  • NewObservation,EVU33,233418

User from RU agency with id 33 made new observation and observation related data can be found in noteelement with id 233418

Dossier Version and Change Set Code relation

With one save action (one update) user can make several changes in the dossier. Changes can be made in different dossier segments which mean that one dossier version can consists from changes belonging to different change categories (typical example for this is when user accept the dossier and promote it with one save action). In such cases, for one dossier version two change set codes will be generated and sent in agency notification message.

All changes that belong to the General category (see Categorization) will be represented with one change set code.

XML Schema

Since change set codes are extension of the existing change set mechanism the codes will part of the change set element. Please find the XML attached (5.2.4...txt).

User scenarios

In this chapter we will describe usual scenarios where user wants to discover if they are interested for the specific notification message or not.

Scenario 1: User is interested for notifications when new path request is created.

Requirements are:

  • New path request. This is change from DossierStateTransition category.
  • Target state is Path Request. The PCS id for Path Request is ‘E’ (can be retrieved using getDossierProcessPhases web service operation)
  • New path requests are issued from the leading RU users.  The id for RU agency is ‘EVU’ (can be retrieved using the “getAgencyTypes” web service operation)

If some of the change set codes matches the following regular expression:

            DossierStateTransition,EVU.*E

path request was created.

Scenario 2: All involved RU refuse the final offer

This kind of scenario cannot be covered only by check of the change set code. Firstly the client should check some preconditions for this scenario:

  • Change was made by RU user
  • The user refused the offer. We should look for “Not accepted” indicator. The id is ‘R’ (values can be retrieved using getAllProgressStatuses web service operation)

The preconditions can be checked using the following regular expression:

            PathIndicatorChange,EVU.*-R

When the precondition is satisfied client should check if:

  • Dossier is in Final Offer
  • All RU’s has ‘R’ value for their progress statuses

With this two-step check client can ensure that the notification is right for him.

Scenario 3: Case when a “late” or “ad hoc” path request enters the post processing phase.

Requirements are:

  • Dossier state transition happened
  • Process type of the target dossier state is “late” or “ad hoc”. The PCS identifiers for process types can be retrieved using the getSupportedDossierProcessTypesMatrix web service operation. The id for late is ‘L’ and for ad hoc is ‘H’
  • Target dossier status is Post Processing. The PCS identifier for this status is ‘J’ (identifier can be retrieved using the getAllProgressStatuses web service operation)

The client should look for change set code that matches the following regular expression:

            DossierStateTransition,EVU.*-[LH]J

Usage of Web Service Notifications

In order to receive notifications via a web service call the following steps have to be performed:

  1. Create a wsdl that implements the IPCSNotificationHandler by using the attached file (5.3 Step 1.txt)
  2. Complete the wsdl file by adding your binding and service information, as it is in for example in the attached file (5.3 Step 2 txt)
  3. Implement and publish your Web Service
  • Note that the request includes the fields username and password. These fields can be used to implement authentication.
  • Your Web Service should return the following status codes:
    • 100 – OK
  • 201 – Error – Dossier not received

5.4 Testing the Notification Web Service

After submitting the “RNE Integration platform communication form” the web service notification feature will be enabled in the Integration Platform.

Afterwards the web service invocation can be tested by changing dossier data in a dossier where the agency is involved in.

File