PCS Integration 7.x Migration guide

Content

PCS Web Services online documentation is available on the following links:

PCS Web Services version 7 - Major version change (published on 1st March 2021)

The change from version 6.1 to version 7 must be done by all integrators starting October 2021. According to the plan, the implementation is scheduled for Q3. We expect to finish the development in September. We will start with the timetable level (introduction of territory element) to have a workable version of the operations and after we will do the rest of the changes. After each sprint, we will be able to provide a version that will be deployed most likely on PCS Test 3, but those versions won't be fully tested yet.

It is a major version change with breaking changes. With the deployment of this version the support for the previous version 6.1 will be discontinued.

This is a major change due to the implementation of planned PCS features for 2021

WSDL/XML Schema changes

Dossier renamed field

  • tt_ru” element is renamed to “tt_applicant

DossierData renamed field

  • leading_ru_id” is renamed to “leading_applicant_id”. This change is in order to distinguish the RU from the Applicant agency.

DossierData new field

  • last_change_username” - The user who last changed the dossier.

Definition of ResponsibleRu complex type in the schema

  • This complex type defines the responsible RU agencies for a given territory.
  • agency_id” - responsible RU agency.
  • transferred_edit_rights” – boolean value used to identify transferred edit rights from an Applicant to the responsible RU in Path Modification process.

RuImPair changes

New fields/complex types
  • responsible_ru_agencies” – list of responsible RU agencies for a given territory.
Changed fields

These changes are in order to distinguish the RU from the Applicant agency.

  • ru_id” is renamed to “applicant_id”.
  • ru_progress_status_id” is renamed to “applicant_progress_status_id”.

DossierAgency changes

New field
  • type” – describes the type of the involved agency which can be “PRODUCTION_ONLY_RU” or “READ_ONLY_IM”. It is valid for RU/IM pair dossiers only.
Removed field
  • production_only” – the logic of this field is replaced by the newly added field “type”.

Timetable changes

Changes in ApplicantTimetable and ImTimetable
  • RuTimetable” complex type is renamed to “ApplicantTimetable”.
  • territory” - introduced the list of territories. The territory is a sequence of paths defined by Applicant-IM responsibility [2].
  • Definition of Territory complex type
    • responsible_applicant_agency_id” – mandatory field for responsible applicant agency in a given territory.
    • responsible_im_agency_id” - mandatory field for responsible IM agency in a given territory.
    • paths” – list of sub-paths (Trasse models) defined in a given territory. Sub-path is a sequence of path sections with the same assigned Applicant-IM responsibility, reference point with at least departure time and running days. It defines a Path on the level of one territory.
    • id” – technical (PCS specific) identifier for the territory and it is suitable only for existing territories.
Trasse changes
Changed field
  • ru_im_pair_id” is renamed to “territory_id” – territory is used to identify the dossier territory for the current path.
New field
  • responsible_ru_agency_id” – is used to identify responsible RU agency for current sub-path (Trasse).
TrasseElement changes
Removed fields
  • responsible_ru_agency_id” and “responsible_im_agency_id”. These fields are moved from TrasseElement to Territory level to avoid repetition.
The following operations are affected from the timetable changes
  • createSingleDossier
  • getDossier
  • getDossierWithReferenceIds
  • updateDossierRUIMPair
  • notifyDossier
  • updatePath
  • updatePathSections
  • createSubPath

TrainParameters changes

Changed fields
  • highest_planned_speed” is a new field in the system and describes the highest defined planned speed of the train.
  • vmax” is renamed to “train_max_speed”.
New fields
  • train_cc_system_id” and “train_radio_system_id” fields are moved from LocoIdent model to TrainParameters model.
  • planned_speed” is added in the train parameters and it has values of “highest_planned_speed” from the schema version 6.1.
  • coasting” – boolean train parameter, entered by the user.

LocoIdent changes

New fields
  • loco_type_id” – unique identifier for the loco type used as train parameter. The list of valid entries can be retrieved through getLocoTypes operation.
  • hybrid_loco_type_id” – identifier for hybrid loco type. The list of valid entries can be retrieved through getAllHybridLocoTypes operation.
Removed fields
  • loco_type_number” – this field is deprecated in LocoIdent model and it is replaced with “loco_type_id”.
  • The “train_cc_syst_id” and “train_radio_system_id” fields are moved from LocoIdent to TrainParameters model.

LocoTypeNumber new field

Added new field “serial_number” and it is used to identify the engine of the locomotive. The default value is “000”.

TrainInformation renamed field

  • ru_alignment_direction” is renamed to “applicant_alignment_direction”. This change is in order to distinguish the RU from the Applicant agency.

CompositionItemCargo renamed field

The existing field “vmax” is renamed to “train_max_speed”.

TimetablePeriod changes

Removed field
  • x4_date” – this field is deprecated in PCS and it is removed from the WS schema.
New fields
  • x4_and_a_quarter" – date which is 4.75 months before start of timetable period.
  • x6_date” – date which is 6 months before start of timetable period.
  • x3_and_a_half_date” - date which is 3.5 months before start of timetable period.
  • x1_date” – date which is 1 month before start of timetable period.
  • start_dossier_creation” – date when starts dossier creation.

Agency changes

Removed field
  • agency_group_id” – agency group entity is deprecated in PCS and this field is removed from the WS schema.
New field
  • country_code" – code of the country to which belongs given agency.

TrafficPeriodDetail removed

TrafficPeriodDetail model is deprecated in PCS and it is removed from the schema.

TrainCCSystCodes renamed field

The element “trainCCSystCode” is renamed to “train_cc_system”.

TrainCCSysteCode changed fields

  • The complex type is renamed to TrainCCSystemCode.
  • Field “trainccsyst_id” is renamed to “id”.
  • Field “trainccsyst_description” is renamed to “description”.

New operations

getAllHybridLocoTypes
  • The operation is used to return all hybrid loco types which can be used in LocoIdent model.

Changed operations

getAllTrafficPeriodsForAgencyGroup
  • The operation is renamed to “getTrafficPeriods” due to a deprecated agency group entity.
  • The response element “trafficPeriodDetailsForAgencyGroup” is renamed to “traffic_period” and the type is changed from “TrafficPeriodDetailsForAgencyGroup” to “TrafficPeriod”.
getTrainCCSystCodes
  • The operation is renamed to “getTrainCCSystemCodes”.
  • The response element “trainCCSystCodes” is renamed to “train_cc_systems”.

Changes in agency notification

In order to have information where the change has happened the format of changeset code PathIndicatorChange is changed.

The new format: PathIndicatorChange,KMXXX,RU_IM_PAIR_ID-AGENCY_ID-PROGRESS_STATUS_FROM-PROGRESS_STATUS_TO

  • KMXXX - agency that did the change (KM - the type of agency; XXX - agency id).
  • RU_IM_PAIR_ID - id of the pair where the change of progress status was changed
  • AGENCY_ID - id of the agency which progress status was changed
  • PROGRESS_STATUS_FROM - old progress status
  • PROGRESS_STATUS_TO – new progress status

Example:

<change_set_code>PathIndicatorChange,KM178,143545-178-U-P</change_set_code>

New status codes

  • 278 UNKNOWN_LOCO_TYPE_ID – Unknown loco type id.
  • 668 TERRITORY_MISSING_RESPONSIBLE_APPLICANT_ID - The request contains territory without responsible Applicant agency.
  • 669 TERRITORY_MISSING_RESPONSIBLE_IM_ID - The request contains territory without responsible IM agency.
  • 680 INVALID_LOCO_TYPE_FOR_IM – Loco type id does not belong to the provided IM agency.
  • 681 UNKNOWN_HYBRID_LOCO_TYPE - Unknown hybrid loco type. Please consult getAllHybridLocoTypes operation for a list of valid entries
  • 682 INVALID_TRAIN_CC_SYSTEM_ID - The request contains path section with invalid train CC system id. The train CC system id should be selected from the assigned loco types.
  • 683 NEIGHBOR_TERRITORIES_WITH_SAME_APPLICANT_IM_COMBINATION - It is not allowed to have neighbors territories with same combination of Applicant and IM.

Upgrade procedure

Existing integrators must adapt their client code to the changed schema.

New URLs

Test systems URL:

Production system URL:

All namespace changed from http://eu/rne/pcs-online/WebServices-v6_1 to http://eu/rne/pcs-online/WebServices-v7

Agency notifications namespace is also changed from http://eu/rne/pcs-online/IntegrationNotification-v6_1 to http://eu/rne/pcs-online/IntegrationNotification-v7

PCS Web Services version 6.1 - Loco type and activity type operations

This change in the schema is in order to support loco type and activity type management through the PCS Web Services. Also, this change does not affect the content of getDossier and notifyDossier operations.

WSDL/XML Schema changes

New operations

The following operations are added to the schema:

  • importLocoTypes
    • The operation is used to add new loco types to the PCS system. Import is allowed only if provided loco types are not present in PCS, otherwise an error will be thrown.
  • updateLocoTypes
    • Used to update multiple loco types in a single step. Update is allowed only if provided loco types are not used in a dossier, otherwise an error will be thrown.
  • removeLocoTypes
    • Used to remove multiple loco types by provided loco type ids. Removal is allowed only if provided loco types are not used in a dossier.
  • getLocoTypes
    • The operation returns loco types by provided search criteria in the request.
  • importActivityTypes
    • The operation is used to add new activity types to the PCS system. Import is allowed only if provided activity types are not present in PCS, otherwise an error will be thrown.
  • updateActivityTypes
    • Used to update multiple activity types in a single step. Update is allowed only if provided activity types are not used in a dossier, otherwise an error will be thrown.
  • removeActivityTypes
    • Used to remove multiple activity types by provided activity type ids. Removal is allowed only if provided activity types are not used in a dossier.
  • getAllTypesOfLoco
    • The operation returns reference data for all possible types of locomotive.
  • getAllTypesOfEngine
    • Reference data operation that returns all possible types of engine used in locomotives.

Changed operations

  • getActivityTypes
    • The operation is used to return activity types by provided search criteria in the request.
    • The namespace has been changed from DictionaryOperations to ActivityTypeOperations.
    • The following fields are added to the GetActivityTypesRequest element:
      • code
      • agency_id
      • ttp_id
    • Field “activityTypes” is renamed to “activity_types” in GetActivityTypesResponse element.

Removed operations

The following operations are removed from the schema. These won't be used anymore as the locations will be synchronized from RNE BigData.

  • updateOperationPoint
  • importOperationPoints

ActivityType model changes

The model is only used in “GetActivityTypesResponse” element and does not affect the content of dossier related operations and notifications.

Renamed fields:

  • "activityTypeId" to "id"
  • "activityTypeDescription" to "description"

New fields:

  • "code" - Activity type code
  • "ttp_id" - PCS specific identifier for timetable period
  • "agency_id" - Responsible agency for the activity type

New status code

  • 676 REFERENCE_ENTITY_ALREADY_EXISTS – The request contains entity for insert which is already defined in PCS.
  • 677 REFERENCE_ENTITY_USED_IN_DOSSIER – The request contains update or remove command for entity, but the entity is already used in a dossier as a reference data.

Upgrade procedure

PCS Web Services version 6.0 - PA/PM operations

This change in the schema is in order to support path modification and path alteration processes through the PCS Web Services.

Path Alteration process

Path Modification process

WSDL/XML Schema changes

New operations

The following operations are added to the schema:

  • adjustValidityPeriod
    • Used to indicate the new validity period for the working copies added during the PA/PM process
  • removeSubPaths
    • Used to remove multiple sub paths by provided sub path ids. Removal is allowed only on sub paths from the same territory

Removed operation

The operation switchToAdjustment is removed from the schema.

Changed operations

StartPathModification removed fields

The following fields are removed from the StartPathModificationRequest:

  • Working_copy_intent
  • Ims_paths_for_modification
  • Path
StartPathAlteration removed fields

The following fields are removed from the StartPathAlterationRequest:

  • Working_copy_intent
  • Ims_paths_for_modification
  • Path

New field in Trasse model

Responsible RU/IM pair id
  • "ru_im_pair_id" - used to identify to which RU/IM pair belongs the current path. This field is updated by PCS system only.

PaPmData model changes

Renamed PaPmData model

The existing PaPmData is renamed to PathPaPmData, because it is used in Trasse model.

PathPaPmData removed fields

The following fields are removed from the PathPaPmData:

  • is_read_only
  • working_copy_intent
  • markedForEditing
PathPaPmData added fields
  • Added field "working_copy" - used to indicate the path that is a working copy during the Path Alteration/Path Modification process. Updated by PCS system only.

RuImPair model changes

Introduced a new model

Added new PairPaPmData model that holds PA/PM information for a given dossier RU/IM pair.

Renamed field

The field "is_process_initiator" is renamed to "process_initiator".

RuImPair moved fields

The following fields are moved from RuImPair to PathPaPmData:

  • process_initiator
  • affected_by_process

New error codes

  • 673 SUB_PATH_CHANGE_IN_PAST_DAYS_IN_PA_PM - Only future days can be changed for sub-paths in PA/PM.
  • 674 SUB_PATHS_FROM_ANOTHER_TERRITORY - The request contains sub path ids that do not belong to the provided RU-IM pair id.
  • 675 TERRITORY_WITHOUT_SUB_PATH - It is not allowed to exist territory without sub path.

New EC behaviours

When the dossier is in path alteration or path modification process with getDossierRequest we will retrieve only the working copies. With that, we will have the same behaviour as on the GUI.

In the path alteration/path modification process when the territory is marked as affected, for sub paths with validity period in the future, we do not keep reference to the origin sub path. Those sub paths will be indicated as new one. The client will be able to edit those sub paths.

During the path alteration/path modification process, when the integrators want to change the calendar, only editing of the calendar days in the future is allowed.

For working copies that have origin path, only editing of calendar days that are in the future is allowed.

Upgrade procedure

Existing integrators must adapt their client code to the changed schema to process path alteration/path modification.

PCS Web Services version 6.0 – Major version change (Published 5th April 2018)

The change from version 5 to version 6 must be done by all integrators starting November 2018.

It is a major version change with breaking changes. With the deployment of this version the support for the previous version 5 will be discontinued.

This is major change due to the implementation of the Envelope Concept in PCS. The conceptual changes are reflected in the usage of PCS Web Services.

Additionally some “spring cleaning” was overdue in the schema and this gave an occasion to do it. Some fields are deprecated, some are rearranged and some types are improved.

WSDL/XML Schema changes

Authentication changes

MatrixCardResponses are removed from AuthenticateRequest. AuthenticateData removed from all response types. Further information about the new authentication process can be found here.

Unification of naming conventions

Complex types are named always in CamelCase while elements_are_underscored. Example: the type for the dossier container is WsDossierContainer <xsd:complexType name="WsDossierContainer">

While the related element in the get dossier response is:

<xsd:complexType name="GetDossierResponse">

    <xsd:sequence>

        <xsd:element minOccurs="0" name="ws_dossier_container"

                     type="d:WsDossierContainer">

Why is this important: remove complex mappings to our Java domain code and consistency. Request/Response elements are not changed to underscore notation from pragmatic reason as they are too many and are not mapped to domain objects.

AgencyID complex type

Complex type defined to combine the choice between Agency PCS or Non PCS (UIC) ID. The new type is used in the schema in all places where a choice was offered:

<xsd:choice>
    <xsd:element name="agency_id">
        <xsd:simpleType>
            <xsd:annotation>
                <xsd:documentation>The id of the c-oss agency that acts on behalf
                    of IM from the pair.
                </xsd:documentation>
            </xsd:annotation>
            <xsd:restriction base="xsd:long">
                <xsd:totalDigits value="12"/>
            </xsd:restriction>
        </xsd:simpleType>
    </xsd:element>
    <xsd:element name="agency_uic_id" minOccurs="0" nillable="true">
        <xsd:simpleType>
            <xsd:annotation>
                <xsd:documentation>The uic id of the c-oss agency that acts on
                    behalf of IM from the pair. Reserved for possible feature usage.
                </xsd:documentation>
            </xsd:annotation>
            <xsd:restriction base="xsd:string">
                <xsd:maxLength value="20"/>
            </xsd:restriction>
        </xsd:simpleType>
    </xsd:element>
</xsd:choice>

New agency_id element of type AgencyId: 

<xsd:element name="agency_id" type="dict:AgencyId"/>

The following fields are now of AgencyId type:

  • CatalogDossierData
    • leading_im_id
  • CatalogTrasseElement
    • agency_id
  • DossierAgency
    • agency_id
  • DossierData
    • leading_im_id
  • RuImPair
    • ru_id
    • im_id
  • TrasseElement
    • responsible_ru_agency_id
    • responsible_im_agency_id
  • CompositionItem
    • agency_id
  • CompositionItemCargo
    • agency_id
  • CompositionFootnote
    • agency_id

Renamed root elements

  • PathfinderIntegration -> renamed to ws_dossier_container
  • Catalogintegration -> renamed to catalogue_dossier_container

Removed fields in Trasse type

Trasse.type field removed due to the removal of Main timetable

The Trasse type is the type of the <path> element in the types that represented the RU and IM timetables. It was used to make the difference between Main timetable and Subsidiaries. With EC concept there are only Sub-path’s so there is no more need for a type field. The naming of the related elements and types were inconsistent. They are now renamed.

  • The element tt_km is renamed to tt_im (tt_ru remains the same)
  • EvuTimetable renamed to RuTimetable
  • KmTimetable renamed to ImTimetable
  • CatalogKmTimetable -> CatalogIMTimetable
Trasse.managedByPcs removed

It is not needed anymore as PaP’s can be added in any Sub-path and it is not locked for editing.

Trasse.processing_status removed

With the introduction of the Pre-booking phase, it can be clearly identified based on the dossier status when the C-OSS is working and when the IM is responsible. Moreover, each has its own timetable.

Remove unused fields
  1. isHarmonized
  2. midnights_arrival
  3. midnights_departure
  4. associated_trains
  5. agency_id
  6. isCalendarConsistent

These fields were not used so now they are removed.

DossierData.train_id -> MOVED to Trasse

The train_id element of type TsiTrainId will be moved from dossier to path element. All paths that belong to one TSI Variant will have the same TsiTrainId, but they will have different TsiPathId. See more details about TSI Variants in the chapters below.

Trasse -> MOVED to PaPmData
  1. is_read_only
  2. working_copy_for
  3. markedForEditing
TrasseElement -> MOVED to CatalogueData

This new type combines catalogue related fields that used to be on <path_section> level in catalogue dossiers. This improvement is purely for clarity and easier debugging and understanding of incoming requests.

  1. corridor_catalogue_id
  2. corridor_id
  3. parameter_set_code
  4. catalogue_path_number
  5. remaining_capacity_id
  6. notrequestedCapacityId
TrasseElement -> MOVED to UsedCatalogueData

This new type combines catalogue related fields that used to be on <path_section> level in dossiers that use path sections coming from catalogues. This improvement is purely for clarity and easier debugging and understanding of incoming requests.

  1. corridor_catalogue_id
  2. corridor_id
  3. originCorridorCatalogueId
  4. catalogueTeId
  5. originCatalogueTeId
  6. paprequest_id
  7. catalogue_selector_agency_id
  8. catalogue_path_number
  9. added_by_agency_id
TrasseElement -> MOVED to Times

Complex type that combines all times and offsets that used to be on <path_section> level. This improvement is purely for clarity and easier debugging and understanding of incoming requests.

  • earliest_arrival_time
  • latest_arrival_time
  • actual_arrival_time
  • actual_arrival_time_offset
  • actual_arrival_manual_offset
  • actual_arrival_timezone_offset
  • actual_departure_time
  • actual_departure_time_offset
  • actual_departure_manual_offset
  • actual_departure_timezone_offset
  • earliest_departure_time
  • latest_departure_time
  • public_arrival_time
  • public_departure_time
  • min_dwell_period_time
TrasseElement -> MOVED to TrainParameters

Complex type TrainParameters is created that combines all train parameter fields that used to be on <path_section> level. This improvement is purely for clarity and easier debugging and understanding of incoming requests.

  • vmax
  • train_length
  • train_load
  • length_of_carriages
  • weight_of_carriages
  • brake_type_id
  • brake_percentage
  • max_axle_weight
  • free_text
  • highest_planned_speed
  • route_class
  • push_pull_train [NEW]
  • min_brake_weight_im_percentage
  • has_emerg_brake_bypass
  • traffic_type
  • type_of_service
  • loco_idents
  • activity_types
  • location_types
  • exceptional_gauging_idents
  • tilting_function_id
  • profile_p1
  • profile_p2
  • profile_c1
  • profile_c2
  • dangerous_goods_indications

TrasseElement removed fields

  • is_reference_point is removed. The first path section is always the reference point
  • earliest_departure_time_offset, latest_departure_time_offset, earliest_arrival_time_offset, latest_arrival_time_offset are removed because they are not taken into account anymore by the system and earliest and latest calendars are not calculated.
  • trafficperiod_id – traffic periods can only be applied via UI and are not tracked in the system anymore. However, this means they cannot be applied via Web services

TrasseElement new fields

Responsible IM agency

responsible_im_id is a new field along the already added responsible_ru_id. Together they replace the agency_id that was used to designate the responsible RU in the RU timetable and the responsible IM agency in the IM timetable. This ambiguity is there for alleviated with the existence of separate fields that will be present in each path section in both IM and RU timetables.

LocoIdnet change

Multiple Train CC systems can be selected for a Loco ident in the common train parameters. Consequently, the train_cc_syst_id field is now unbounded and should be mapped to a list.

Construction starting point

is_construction_starting_point

Alternative origin or destination
  • alternative_origin
  • alternative_destination

These are new fields that are needed to take advantage of new dossier structures with multiple Origins and/or Destination, I-Train, X-Train etc., that are supported by the Envelope concept.

Times

New times defined according to TSI requirements: public_arrival_time and public_departure _time.

Timezone offsets
  • actual_arrival_timezone_offset
  • actual_departure_timezone_offset

New fields to allow the definition of specific timezone in which actual arrival and departure times are defined. These are fields that can be set by the integrators or users. They are numeric fields that represent timezone offset expressed in hours relative to UTC+1.

Manual offsets
  • actual_arrival_manual_offset
  • actual_departure_manual_offset

New fields that allow the definition of actual arrival or departure times offset of the calendar by the integrators or users.

Common train parameters changes

New common train parameter introduced in the schema due to TSI requirements:

  • push_pull_train – type boolean

DossierData type changes

New complex type TrainInformation combines the following fields that were definer directly in <dossier_data> level.

  • valid_period
  • route
  • train_name
  • ru_alignment_direction
  • im_alignment_direction

Decorative elements of WsDossierContainer and CatalogueDossierContainer

Since we do not track traffic periods that are applied to a calendar item of a path section anymore on <path_section> level the related traffic periods decorative element is removed.

CreateSubPath operation

CreateSubsidiary operation and all related types are renamed to CreateSubPath.

Removed operations

The following operations are either not implemented at all (except in the schema) or are not used:

  • removeDossier
  • createDossier (createSingleDossier should be used instead)
  • getGoodsTypesByDescription
  • getRegBodiesForDossier
  • importTrafficPeriods
  • getRegBodiesForIMAgency
  • getProdAgencyUserDataForDossier
  • getIMUserDataForDossier

New status codes

  • 659 INVALID_DWELL_TIME - The dwell time is less than the difference between the departure and the arrival times.
  • 660 ONLY_RU_SHOULD_HAVE_COMMERCIAL_STATUS - Only RUs should have commercial status.
  • 661 ONLY_RU_IM_PAIR_BASED_DOSSIERS_HAVE_PROGRESS_STATUS - u-im pair based dossiers should only have traffic lights on ru-im pair based level only.
  • 662 ONLY_RU_SHOULD_HAVE_PRODUCTION_FLAG - Only RUs should have production only flag set.
  • 663 RU_IM_PAIR_BASED_DOSSIERS_INVALID_DOSSIER_STATUS - Ru-im pair based dossiers contain dossier status on ru-im pair based level only.
  • 664 RU_IM_PAIR_BASED_DOSSIERS_INVALID_PROCESS_TYPE - Ru-im pair based dossiers should have process type set on ru-im pair level only.
  • 665 PRODUCTION_AGENCY_ALREADY_INVOLVED_IN_DOSSIER_PAIRS - Production agency already exists in the dossier.
  • 700 INCONSISTENT_CALENDAR - Calendar inconsistency error code for acceptance indicator update to green. This error code prevents an agency to accept the dossier when they have an inconsistent calendar in the Sub-paths in one of the territories under their responsibility. It is not possible in PCS anymore after the implementation of the Envelope concept to have an IM timetable with less offered running days in a middle territory.
  • 701 INCONSISTENT_RESPONSIBLE_RU_IM – Incorrect responsible RU/IM agency in path section

New EC behaviors

When the calendar of one or more sub-paths is changed or new sub-path(s) with calendar are created via Web Services the system will switch out any added running days that are covered in already existing sub-paths.

Acceptance indicators will be downgraded for neighboring territories when relevant information on the borders of territory are performed via Web services.

Other clean up

  • ThroughCoaches are removed
  • Remove GetDossier.pathsWithResponsibleRu and UpdateDossierRUIMPairRequest.updateImPathBasedOnResponsibleRU. These options were introduced for the support of IM integrators that are paired with multiple RU’s. This is now the usual way of work with Envelope concept so these special options are not needed anymore.
  • dossierRUIMPair element is now defined with DossierRUIMPair type instead of a reference type in the UpdateDossierRUIMPairRequest
  • change_sets reference type defined as a ChangeSets type in NotifyDossierRequest
  • RuimpairCOssEntry.is_active field is removed as it is not used anymore after the introduction of the Pre-booking phase
  • RuImPair.ruimpair_c_oss_entries is removed. Only one entry is allowed as only one C-OSS can be involved in the pair.

Upgrade procedure

Existing integrators must adapt their client code to the changed schema. Their use cases must take into account that there is no more Main timetable and with that, there is no more complimentary calendar.

International paths cannot be created anymore. Only in createSingleDossier operation, a path element with path sections with different responsible RU-IM pair can be sent.

The implementation of the Envelope concept changes the way of work, especially of RU agency integrators. The changes from IM agency integrators point of view should be more from technical nature to support the new schema and handle the new status codes.

New URLs

Test systems URL:

https://pcstest1.rne.eu/pcs/services/PcsWebServices_v6?wsdl

Production system URL:

https://pcs-online.rne.eu/pcs/services/PcsWebServices_v6?wsdl

All namespace changed from: http://org/railneteurope/pathfinder/IntegrationProxy-v5

To: http://eu/rne/pcs-online/WebServices-v6.

Agency notifications namespace is also changed from:http://org/railneteurope/pathfinder/IntegrationNotification-v5

To:  http://eu/rne/pcs-online/IntegrationNotification-v6

New Operations and TSI Identifiers

It is yet to be specified how the TSI integration will be supported in a better way with additional operations and this is not yet reflected in the schema. DRAFT!

This is a proposal for additional types that could be implemented in the schema to support the new operations.

Path is common parent type from which the specific types will inherit and it contains all common fields.

Trasse models the Sub-path according to the Envelope concept. Has single responsible RU-IM pair.

PathVariant is the formerly known as Timetable combination in PCS, it did not exist in the Web Services schema.

UserVariant uniquely combined PathVariant that consists of Sub-paths that only belong to it and not other PathVariant.

TSIVariant composed of multiple Sub-paths with single responsible RU-IM pair but same TSI Variant identifier.

GetPathVariants

  • To be used by RNE for warehouse purposes
  • To be used by anyone who needs to get Path Variants constructed by PCS

CreateUserVariant

  • Used by leading RU in Open phase

UpdateUserVariant

  • Used by leading RU in Open and Harmonization

GetTsiVariants

  • Used by TIL or RU’s integrated via PCS without CI/TIL

Please find some examples on this link.

PCS Integration 5.5 Migration guide (Published 1st September 2017, updated 2nd October)

Version 5.5 is not an actual new version, but “retrograde” non-braking changes to the version 5 schema. Changes are expected to be deployed in November 2017.

WSDL/Xml Schema changes

We all know that working with PA/PM process was unclear and difficult through WS.

This version contains changes that will make working with PA/PM process easier and give you possibility to go through the whole process. For the actions that are not mentioned here, like updating of the working copies, creating new subsidiaries, updating progress status, updating dossier status, integrators should use already available operations.

In order to make it possible we will introduce new operations:

  1. startPathModification - this operation should be used for triggering Path Modification process by RUs. Following input will be expected in order to start PM
    1. <processInitiator> - Mandatory element, used to indicate the initiator of the process. Should be id of the pair where user is involved and pair without c-oss
    2. <pathModificationTypes> - Mandatory element
      1. <pathModificationType_id> - indicates the reason for starting PM. Helper operation getPathModificationTypes should be used to get all possible Path Modification types
    3. <affectedPairs> - Mandatory element
      1. <pairId> - indicates the pair that should be marked as affected in process of PM
    4. <workingCopyIntent> - Mandatory element, used for defining PM process as Replacement or Adjustment (indicates the intent of the working copy)
    5. <imsPathsForModification> - Optional element, that must be defined in case of PM process started as Replacement. If not defined an error code will be returned
      1. <imPathId> - indicates the path that should be marked for editing
    6. <path> - Optional element, that must be defined in case of PM process started as Adjustment. If not defined an error code will be returned. Used for defining a subsidiary that will be created as a result of the PM process started as Adjustment.
    7. <dossier_id> - Mandatory element, that indicates dossier for which PM process is started
    8. <authenticateData> - Contains information needed for authentication
  1. startPathAlteration – should be used for triggering Path Alteration process by IMs. Following input will be expected in order to start PA:
    1. <processInitiator> - Mandatory element, used to indicate the initiator of the process. Should be id of the pair where user is involved and pair without coss
    2. <pathAlterationTypes> - Mandatory element
      1. <pathAlterationType_id> - defines reason for starting PA. Helper operation getPathAlterationTypes should be used to get all possible Path Alteration types
    3. <affectedPairs> - Mandatory element
      1. <pairId> - indicates the pair that should be marked as affected in process of PA
    4. <workingCopyIntent> - Mandatory element, used for defining PA process as Replacement or Adjustment (indicates the intent of the working copy)
    5. <imsPathsForModification> - Optional element, that must be defined in case of PA process started as Replacement. If not defined an error code will be returned
      1. <imPathId> - indicates the path that should be marked for editing
    6. <path> - Optional element, that must be defined in case of PA process started as Adjustment. If not defined an error code will be returned. Used for defining a subsidiary that will be created as a result of the PA process started as Adjustment.
    7. <dossier_id> - Mandatory element, that indicates dossier for which PA process is started
    8. <authenticateData> - Contains information needed for authentication
  1. processPathModificationOffer – should be used for accepting/rejecting PM Offer by RUs. Following input will be expected:
    1. <action> - Mandatory element, used to indicate if PM Offer is going to be Accepted or Rejected ('A' or 'R')
    2. <pathModificationOfferRejectionCauses> - An optional element, that must be defined in case of PM Offer Rejection by RUs. If not defined an error code will be returned. Helper operation getPathModificationRequestRejectionCause should be used to get all possible Path Modification rejection causes.
    3. <rejectionReason> - An optional element, that must be defined in case of PM Offer Rejection. If not defined an error code will be returned.
    4. <dossier_id> - Mandatory element, that indicates dossier for which processing of PM offer is done.
    5. <authenticateData> - Contains information needed for authentication
  1. processPathAlterationOffer – should be used for accepting/rejecting PA Offer by RUs and withdrawing PA offer by IMs. Following input will be expected:
    1. <action> - Mandatory element, used to indicate if PA Offer is going to be Accepted or Rejected ('A' or 'R')
    2. <pathModificationOfferRejectionCauses> - An optional element, that must be defined in case of PA Offer Rejection by RUs. If not defined an error code will be returned. Helper operation getPathAlterationRejectionCause should be used to get all possible Path Alteration rejection causes.
    3. <rejectionReason> - An optional element, that must be defined in case of PA Offer Rejection. If not defined an error code will be returned.
    4. <dossier_id> - Mandatory element, that indicates dossier for which processing of PA Offer is done.
    5. <authenticateData> - Contains information needed for authentication
  1. askForOfferAdaptation – should be used for performing PM/PA Offer Adaptation. Following input will be expected in order to processed Offer adaptation:
    1. <reason> - Mandatory element, used for defining the reason for PM/PA Offer Adaptation
    2. <dossier_id> - Mandatory element, that indicates dossier for which PA/PM Offer adaptation is made.
    3. <authenticateData> - Contains information needed for authentication
  1. switchToAdjustment – should be used for changing PA/PM type of change from Replacement to Adjustment. This action will be possible only if PA/PM process was started as Replacement and train has already started to run. Following input will be expected in order to processed switching to Adjustment:
    1. <validityPeriod> - Mandatory element, used to indicate the new validity period for the working copies
    2. <dossier_id> - Mandatory element, that indicated id of the dossier
    3. <authenticateData> - Contains information needed for authentication
  2. rejectPathModificationRequest – should be used for rejecting PM Request by IMs. Following input will be expected:
    1. <pathModificationRequestRejectionCauses> - Mandatory element, reasons for PM Request rejection by IMs. Helper operation getPathModificationRequestRejectionCause should be used to get all possible PM Request rejection reason types.
    2. <rejectionReason> - Mandatory element, that indicates reason for PM Request rejection.
    3. <dossier_id> - Mandatory element, that indicates the dossier for which PM Request rejection is done.
    4. <authenticateData> - Contains information needed for authentication

Removed optional fields:

As we have mentioned above, we have added dedicated PA/PM operations. As a result of new added operations, there were optional elements in DossierRUIMPairElement that were not needed anymore. Elements that were removed are:

  • pathAlterationTriggerRequest
  • pathModificationTriggerRequest
  • pathAlterationOfferRejectionCauses
  • pathModificationRequestRejectionCauses
  • pathModificationOfferRejectionCauses

New status codes:

  • 653 INVALID_WORKING_COPY_INTENT - Provided working copy intent is not valid (Replacement and Adjustment are valid one)
  • 654 INVALID_PROCESS_INITIATOR - Set ruim pair id is not valid process initiator
  • 655 INVALID_DOSSIER_RUIM_PAIR_ID_MARKED_AS_AFFECTED - Dossier RUIM pair id marked as affected is not valid (doesn't belong to dossier or it belongs to pair with COSS).
  • 656 MISSING_ADJUSTMENT_PATH - Path that should be created as Adjustment is missing.
  • 657 INVALID_ACTION_PROCESSING_OFFER - Action in processing PA/PM Offer is not valid. Should be 'A' or 'R'.
  • 658 UNSATISFIED_TRANSITION_CONDITIONS - Transition cannot be proceed, because there are conditions that are not satisfied.

Upgrade procedure

Only agencies that want to use PA/PM process through WS need to make effort to support the new added operations. The changes are backwards compatible and other agencies should continue using the endpoint V5 without any efforts.

PCS Integration 5.4 Migration guide (Published 24th July 2017)

This version is the so called "IP Consolidation package". Changes are expected to be deployed in Production with Major Release 2017.

WSDL/Xml Schema changes

Deprecated status code:

  • 102 - This status code will never be generated by the web services anymore, the updates after reasonable reconstruction of missing data (missing RU paths, missing other agency/pair path sections) will either return 100 or 302 if a change for which the user does not have permissions was sent. This will significantly improve especially updating dossiers with PaP’s. Fix PaP fields can now also be updated in-line with the ACL rules already implemented in the web application.

New status codes:

  • 649 INVALID_BLOCKS_PATH - Partial request sent with incorrect blocks. Probably a block is missing in between that cannot be reconstructed. This error may be raised only in dossiers with such structure in paths that disjoint blocks with same responsible agency exist.
  • 650 NO_CHANGES_FOUND - no changes found in the request, dossier version won't be saved.
  • 651 INVALID_TRAIN_PARAMETER_VALUE_IN_TERMS_OF_CATALOGUE_TRAIN_PARAMETERS - Train parameters value not valid of terms of catalog train parameters
  • 652 INVALID_PATH_STRUCTURE - IM agency tries to create international subsidiary or subsidiary where they are not involved

Upgrade procedure

All integrators must use the only available endpoint for version 5.1. All previous versions have been removed, including version 5.0.

Test system URL:

https://pcstest1.rne.eu/pcs/services/IProxyIntegrationService_v5_1?wsdl

Web service MTOM and security enabled endpoints were also removed.

TAF-TSI test system URL: 

https://pcs-taftsitest1.rne.eu/pcs/services/IProxyIntegrationService_v5_1?wsdl

Production system URL (updated 12th October 2017):

https://pcs-online.rne.eu/pcs/services/IProxyIntegrationService_v5_1?wsdl

Flat file and FTP communication channels are not supported anymore. These were never used in the production system. One agency can now use both email and web service communication channels.

PCS Integration 5.3 Migration guide (Published 12th May 2017)

Same as 5.2, this not an actual new version, but “retrograde” non-braking changes to the version 5 schema. Changes are expected to be deployed in Production with Major Release 2017.

WSDL/Xml Schema changes

  1. In DossierData under <international_train_nr> element, a new optional element <trainid> is added. <trainid> is mandatory element and it should be defined during the process of dossier creation. If <trainid> is not defined an error code (TRAIN_ID_IS_NOT_DEFINED - 645) is returned. Modification of the <trainid> is possible only in Open phase (by Leading RU), after releasing the dossier to Harmonization the editing of the <trainid> is disabled. <trainid> consists of following elements:
    1. <objectType> - Provides a possibility for differentiation between the objects. This element is not defined by the user, it is resolved by PCS. For <trainid> it has value TR.
    2. <coreElement> - It is the main part of identifier and is defined by the company that creates it.
    3. <variant> - Mandatory element, with default value ‘00’. Value can be changed by the user.
    4. <timetableYear> - Refers to the timetable period of the dossier and is not defined by the user, it is resolved by PCS.
    5. <startDate> - An optional element that is only used for preparing the daily (operational) object.
    6. <companyCode> - Mandatory element that is entered by the user. As value should be set RICS or UIC code of RU agency.
  2. The Trasse element under <type> element has new optional element <tsi_path_id>. Modification of <tsi_path_id> depends on the timetable and the agency. <tsi_path_id> consists of following elements:
    1. <objectType> - Provides a possibility for differentiation between the objects. This element is not defined by the user, it is resolved by PCS. For RU Paths <tsi_path_id> has value PR, for IM Paths has value PA.
    2. <coreElement> - It is the main part of identifier and is defined by the company that creates/edits it.
    3. <variant> - Mandatory element, with default value ‘00’. Value can be changed by the user.
    4. <timetableYear> - Refers to the timetable period of the dossier and is not defined by the user, is resolved by PCS.
    5. <startDate> - An optional element that is only used for preparing the daily (operational) object.
    6. <companyCode> - Value for this element is resolved by PCS. As value is set owner of first path section (in case of RU Path – responsible RU, in case of IM Path responsible IM).

Upgrade procedure

In order to not force agencies to use TAF/TSI features there is configuration property which tell are TAT/TSI features mandatory or not. Only on the systems where TAF/TSI features are configured as mandatory, agencies need to make effort to conform to the additional elements (<trainid>) that are effectively mandatory, but optional in the schema. If TAF/TSI features are not configured as mandatory agencies should continue using the endpoint V5 without any efforts.

When environment (currently TAF-TSI test system only) is configured with TSI mandatory then the Train Id and Path Id are mandatory for RU's since the dossier creation and can only be edited in Open phase (let's say change start date etc.) but cannot be removed. For IM's as part of the fix that we are preparing we will reset them so even, if they do not sent them no error is returned because IM's can never change them anyway.

When the environment is set to optional, which will be the case in Production, the leading RU may create/change them during creation and Open phase, but they can also remain empty. If they are set then after Harmonization nobody can remove/change them.

PCS Integration 5.2 Migration guide (Published 10th February 2017, updated 16th March 2017)

This is not an actual new version but “retrograde” non-braking changes to the version 5 schema. Available in production.

WSDL/Xml Schema changes

In case when one IM agency is paired with multiple RU agencies there is a need to only send partial update based on the responsible RU agency indicated by the dossierRUIMPair that is sent as element of updateDossierRUIMPairRequest. With this partial update the other blocks of the path that will be absent in the request won’t be modified by PCS IP. This is different from the current behavior that presumes that all path sections that are missing in the request and are under the responsibility of the IM agency that is sending the request, will be deleted.

To accommodate this case the following changes to the schema are made:

  1. In TrasseElement a new optional element <responsible_ru_agency_id> or <responsible_ru_agency_uic_id> is added, before <agency_id> or <agency_uic_id> element. It is the id of the RU agency responsible for the given path section. This field is not supported in the notification messages, only in getDossier operation.
  2. The request type for the getDossier operation, GetDossierRequest, has new optional boolean parameter pathsWithResponsibleRu. When set to true it indicates that <responsible_ru_agency_id> element should be included in all elements of type TrasseElement for the dossier in the response.
  3. The request type for the updateDossierRUIMPair operation, UpdateDossierRUIMPairRequest, has new optional boolean parameter updateImPathBasedOnResponsibleRU. By setting it to true you can indicate that the update of IM paths should be based on the responsible RU agency.  This will work only if responsible RU agency is set in all elements from type TrasseElement for the dossier in the request (element <responsible_ru_agency_id> or <responsible_ru_agency_uic_id>) This element is needed to ensure that the sent block (the one that needs to be updated) is resolved correctly on both sides, the client and PCS IP. All path sections that do not have the same responsible RU agency as the one from the RU-IM pair in the request won’t be touched.

Examples:

The intention is that in one of the next major versions the new elements <responsible_ru_agency_id> or <responsible_ru_agency_uic_id> in TrasseElement type will become non optional and additional non optional elements will be added <responsible_im_agency_id> or <responsible_im_agency_uic_id> for the responsible IM agency for each path section.

Upgrade procedure

Only agencies that need the specific behavior described in the previous chapter need to make effort to conform to the additional optional elements in the schema. The changes are backwards compatible and other agencies should continue using the endpoint V5 without any efforts.

PCS Integration 5.1 Migration guide

PCS Integration version 5.1 doesn't cover any change in the WSDL/Xml schema. Changes of the PCS Integration 5.1 are documented in the PCS IP Handbook. Version 5.1 contained only new helper operations and new values in the notification service. Available in production.

PCS Integration 5.0 Migration guide

No longer supported version.

WSDL/Xml Schema changes

PCS Integration version 5.x covers changes from different PCS features which are documented in separate chapters.

 There is no backward compatibility in this version. Available in production.

National IM parameters

New elements are added on <national_im_parameter> element:

-         <minLength>, <maxLength> that are used for length restriction of string and number parameter types

-         <format> that is used for the format of the new date, time and datetime parameter types

-         <description> that is used for the description of the IM parameter

-         <conditionalExpression> that contains the parent types and their values. Currently one IM parameter can depend on other IM parameter or dossier Train Type. There can be more than one parent parameter in the relationship and the operator used to test the condition is "AND".

-         <isHidden> indicates if IM parameter is hidden

The changes in national_im_parameter affects <ru_im_pair> and <path_section> elements. Additionally all getIMParametersXYZ will be adjusted:

-         getImParametersForAgencyUicCodeForTimetablePeriod

-         getImParametersForAgencyUicCode

-         getImParametersForTimetablePeriod

-         getImParameters

C-OSS and catalogs

New elements:

-         <rnecName> and  <rfcName> in <corridor> element that indicate the RNE-C and RFC corridor names correspondingly

-         <isRfcValid> element that indicates if corridor is valid RFC

-         <returnCapacityPeriod> in <corridor> element that indicates the period for automatic return of RFC capacity

-         <notrequestedCapacityId> in <path_section> element that indicates the capacity that is still not used (not assigned) in dossier. This is used to pre-reserve the capacity for Late and AdHoc dossiers where the first RU that uses the capacity in the dossier actually gets it (reserved) once when dossier is promoted to Path Request.

-         <originCatalogueTeId> and <originCorridorCatalogueId> in <path_section> element Indicates the catalogue identifiers for the originating catalog. Used in Combined PaP -  when RU request an extra capacity or C-OSS selectes Not avaialbale days.

-         <catalogueTeId> in <path_section> element that references the catalogue origin path section.

-         <reservationType> in <papRequest> element – helper field that indicates if PaP was reserved as originally requested or RFC reserved an alternative.

-         <managedByPcs> in <path> element that indicates that the path was created by PCS for Combined PaP purposes and will be managed by PCS. This path cannot be updated by PCS users. It is true for paths that resulted from path split operation due to not available days.

Process related

The following elements were added on <path> element:

-         <isMainRouteRespected> that indicates that detailed master route is not respected. For more information please check section “Consistency of the subsidiary path“ from https://pfcoretest.railneteurope.info/docs/pcs-4-0.pdf.

-         <isCalendarConsistent> that indicates that subsidiary calendar in detailed master structure is not consistent. For more information please check section “Consistency of the subsidiary calendar” from https://pfcoretest.railneteurope.info/docs/pcs-4-0.pdf.

On <path_section> element were added following elements:

-         <isBorder>  that indicates if path section is border, i.e. has neighbor section for which other agency is responsible

-         <isHarmonized> that indicates the harmonization status for the border point.

The <observations> element is added in <noteelement>. Single <observation> element contains the following elements:

-         <imIds>

o    Single <imId> indicates the affected IM

-         <pathIds>

o    Single <pathId> indicates the affected path

-         <types>

o    Single <type> indicates the observation type

-         <isJustified> that indicates if the observation is justified

The decorative <timetableperiod> was extended with the following new elements:

-         <x_2_date>

-         <x_4_date>

-         <x_5_date>

-         <x_7_5_date>

-         <x_8_date>

-         <x_11_date>

New element <marked_for_editing> was added in <path> that indicates the selected (when initiating the process) or changed (during the process) path in PA/PM processes.

 

Upgrade procedure

Procedure for existing integration efforts

V5 endpoint is designed to address the new functionalities that are described above. However, it also supports all functions available in previous version 4.2 and it is a complete replacement for it.

This version is not backward compatible with older versions and integrators that decide to migrate to v5.0 will have to adjust their systems to the new schema.

 

Procedure for new integration efforts

Major version v5 endpoint should be used for new integration efforts for both WS-mediation and agency notification.

The major versions v4.x and below should not be used for new integration efforts at all. Once the existing integrators move away from using these endpoints, they will be decommissioned.

PCS Integration 4.2 Migration guide

PCS Integration version 4.2 covers the management of dossiers that are using Flex PaPs. No longer supported version.

WSDL/Xml Schema changes

The Flex PaP data is provided in form of new optional elements and fields. In order to retrieve this data use the new optional field <getFlexPaPData> in getDossier and getDossierWithReferenceIds operations.

The new decorative element <corridor_catalogs> is added in the umbrella element <pathfinderintegration>. The single <corridor_catalogue> element contains the following fields:

  • <dossiertype_id> that identifies the dossier type of the PaP. This field can be used to identify if used RFC is Fix or Flex.
  • <processtype_id> that identifies the process type of the PaP.
  • <direction> that identifies the direction of the corridor  section
  • <origin_oppoint_id> that identifies the origin operation point of the PaP
  • <destination_oppoint_id> that identifies the destination operation point of the PaP

New <is_protected> field is added in the <path_section> element. This field indicates the protected locations that cannot be neither updated nor deleted.

New <added_by_agency_id> field in the <path_section> element. This field is valid only for intermediate path section and gives the id of the agency that added the path section.

PCS Integration 4.1 Migration guide

PCS Integration Platform version 4.1 covers several change requests and minor usability improvements in the xsd. No longer supported version.

WSDL/Xml Schema changes

New operation getDossierAttachment is introduced that is used to retrieve the dossier attachments. The request needs the attachment id that should be retrieved from the dossier (getDossier operation).

New operation getAllDossiersExtended is introduced as an extension for the existing getAllDossier. The new operation has new fields that enable the user to get dossiers by process type(s) and train type.

The systems which use major version v4 can continue to operate normally but the new operations would not be available.

Operation point in operationPointLocal

New field <from_op_id> is added in the <operationpointLocal> element. The users that want to start using this field should do the following in order to enable communication with PCS in both directions:

  • Send true in <usePcsOpPointIdInOperationPointLocal> field in getDossierWithReferenceIdsRequest.
  • Notify the PCS support team to configure the PCS IP notification system to provide this field in the notification messages

Please note that this field is also available in version 4.0 and the migration to 4.1 is not necessary in order to use it.

Functional changes

Utilizing reference id in operation points decorative element

The decorative element <operationpoint> contains field <reference_id> that was not used. Starting from 03.11.2014 (PCS Core 4.1) each newly saved dossier version will contain reference id value in the <operationpoint> element.

Operation point activity check change

In PCS each operation point has its validity period defined with the fields valid_from and valid_to. Prior to this version the validity period was checked against today’s date, i.e. the operation point is valid if today is inside the validity period.

Starting from this version the validity period is checked against the timetable period. The operation point is valid if:

  • operationpoint.valid_from <= timetableperiod.firstdate and
  • operationpoint.valid_to <= timetableperiod.lastdate

PCS Integration 4.0 Migration Guide

PCS Integration Platform 4.0 version is compatible with PCS Core 4.0. No longer supported version.

The most important new functionalities in PCS Core 4.0 are:

  • Main/subsidiary timetables (calendar consistency)
  • Dossiers that use Pre-arranged Paths (PaP)
  • Composite relations

The new functionalities are available for dossiers with the following combinations of process type and timetable period:

Process Type

Timetable Period

New

2015

Late

2015

Adhoc

2014

 

Fig: Dossiers which support for new functionalities

WSDL/XML Schema changes

XML Schema changes

Following elements were added in the <pathfinderintegration> umbrella element:

  • Decorative <paprequests> element which contains all PaP request models for the dossier.
  • Decorative <corridors> element which contains all corridors related with this dossier.

Following changes were done in the <dossier> element and its children:

  • New <compositerelations> element that contains the composite relations where dossier is included. One <compositerelation> element contains:
    • <type> field that identifies the composite relation type
    • <name> field for the composite relation name
    • <note> field used for comment
    • <starting_dossier_id> field that identifies the dossier from which this relation was initiated
    • <compositerelation_dossier> elements, one for each dossier that is part from this composite relation
  • New <paprequest_id> field in <path_section> element. This flag is valid for path sections that were created using PaP catalog insertion action that resulted in PaP request.
  • New <remaining_capacity_id> field in <path_section> element that is an identifier for the calendar item. Valid only for PaP dossiers and represents the remaining days from the offered capacity on this path section.
  • New <corridor_id> field in <path_section> element. Represents a corridor to which this path section belongs. Used for both, corridor catalog dossiers and dossier that use (assigned) corridor catalogs.
  • New <corridor_id> field in <dossier> element. This field will be used for corridor catalogues and will enable to differentiate between corridor catalogs (RNE corridor catalogue, RFC) and non-corridor ones.
  • New <ruimpair_c_oss_entry> element in <ru_im_pair> element that represents the C-OSS agency that is working on behalf of the IM in the parent dossier RU IM pair.
  • New <leadingcoss_id> field in <dossierdata> element that represents the leading C-OSS agency.
  • New <leadingcoss_uic_id> field in <dossierdata> element that represents an alternative way of entering the leading C-OSS agency. Using UIC agency code instead of          Pathfinder-specific id. Reserved for possible feature usage.
  • New <processing_status> field in element <path> used only for paths with path section(s) imported from PaP catalogue dossiers, to indicate processing status of the path.
  • New <type> field in element <path> used for timetable type, i.e. whether the path is master or slave (or complementary slave).

Upgrade procedure

Procedure for existing integration efforts

v4 endpoint is primarily designed to address the new functionalities (described above).

However, it also supports dossiers without main/subsidiary timetables, i.e. it is a complete replacement for v3 endpoint.

Procedure for new integration efforts

Major version v4 endpoint should be used for new integration efforts for both WS-mediation and agency notification.

The major version v3 should not be used for new integration efforts at all. Once the existing integrators move away from using this endpoint, it will be decommissioned.

File