Inventory

Inventory deals with quotas, a quota is a limit on the number of instances of something that can be reserved at once. A quota will usually have some sort of geographic component, and it will always be associated with a particular departure. For example, one could define a quota on regular tickets for the train leaving Bergen for Oslo at nine o'clock in the morning on the 1st of January 2019. This quickstart will show how to insert your first quota for a fictional transportation company.

Authentication

The Inventory requires a Bearer Token in the Authorization header created by the Entur Authentication server for every request.

Creating departure information

Quotas are added on specific departures. A departure is a single instance of a train or other vehicle leaving its first passenger-carrying stop at a predetermined time and date. A departure is always associated with a line. A line is an ordered list of physical stops that may be visited during a journey. Whether a train actually stops at a given stop on a line is not known by the Inventory module. The Inventory is not the source module for departures and lines, but it needs to have an up-to-date view of both in order to function properly.

Inserting a line

Before one can define a quota one needs departure information. A departure is dependent on knowing which stops the departure could possibly stop at, the line for the departure. All lines are defined in the journey planner, but also have to be defined in the Inventory module, as it is required to be able to calculate the stock between an origin and a destination.

The identification used for the line should be the same as in the journey planner module. The stops are given on the format from the National stop register, in an ordered list from start to end. It is possible to use a line in the reverse order as well, this is defined when inserting a departure, so it is not necessary to add the inverse line.

POST /v1/lines

In this example we imagine there exists a line in the journey planner with the id "ABC:Line:1". The version is set to 1 as this is the first version of this line added to the Inventory. On this line we imagine three stops, "Oslo S", "Lillestrøm stasjon" and "Kløfta stasjon", which have the NSR-codes "NSR:StopPlace:337", "NSR:StopPlace:451", and "NSR:StopPlace:553".

After this request is processed, we should receive a 201 Created with the entity. The line is now ready to be referenced from a departure.

Inserting a departure

The departure is the key in the inventory. A departure is a single instance of a train or other vehicle leaving its first passenger-carrying stop at a predetermined time and date. A departure is always associated with a line.

The identification of the departure is the original dated service journey that is created in the timetable module. The line id is the same that was defined when inserting the line. One also have to define which direction of the line is used for the departure. If the departure uses the line in the order defined when inserting the line information, the invertedDirection field is set defined as false. If you want the departure to use the line in the opposite order the invertedDirection field is defined as true.

POST /v1/dated-service-journeys

In this example we imagine there exists a departure "ENT:DatedServiceJourney:2838" in the timetable. We define this departure to use "ABC:Line:1" in the same direction as above, starting at Oslo ("NSR:StopPlace:337").

After this request is processed, we should receive a 201 Created. The entity including line information is returned, and the departure is now ready for use.

Both Line and Departure are resources created by Entur and there really shouldn't be any need for you to create these yourself.

Creating a quota

Inserting basic quota

One of the simplest types of quota is a quota only meant to limit the capacity of a departure. In the following section we will create a simple quota with a stoplist. A quota with a stoplist release the resource when a reservation is not using it. If a user reserves the resource in the first half of a journey (e.g. Oslo to Lillestrøm), it is still available for others in the second half (e.g. Lillestrøm to Kløfta). We will now create a quota where the useStoplist-flag is true.

In this example we create a quota for the product "ABC:PreassignedFareProduct:Ticket", with 10 available entities. We do not define anything in the "ods", as this is more complex behaviour. You can read more about this in the quides section.

Since we won't nest the product with any other products we don't need a quota configuration. The quota needs to have the flag "useStoplist" set as true, this means that you have a limitation of 10 of "ABC:PreassignedFareProduct:Ticket" between each stop in the stoplist. The stoplist used is the one associated with the departure "ENT:DatedServiceJourney:2838".

POST /v1/quotas

Congratulations! You have inserted your first quota!