Serials Management module

Description:

This module provides the ability to create and manage serial records, which provide mechanism to:

Create a serial record
Link a Purchase Order Line to a serial record
Create a publication pattern for a serial record including:
- Recurrence rules (governing how often and on which days, an issue of the serial is published - e.g. 'Weekly publication, published on a Monday')
- Issue ommission rules (governing any exceptions to the recurrence rules which leads to an issue to be omitted from the publication schedule - e.g. 'not published on the 25th December')
- Issue combination rules (governing any situations where two or more issues are combined into a single physical issue - e.g. 'July and August issues combined into a single summer "July/August" physical issue')
- Issue labelling based on enumeration and chronology rules (governing how each issue is labelled - e.g. '12 issues numbered 1-12 in a volume, 1 volume per year, labelled as "Vol. <vol number>, Issue <issue number>, <month> <year>"')
Generate a set of predicted issues for a period of time (usually 1 year) including all omissions, combinations and labelling
Use each predicted issue to create one or more receiving issues in the Acquisitions Receiving Module

Documentation:

API documentation:

https://dev.folio.org/reference/api/#mod-serials-management

Data migration / automated population of data

Serial record

The first step when populating the serials module with data is to create a serial record. A serial record must exist before a publication pattern can be added and so is the first step. The serial can optionally be linked to a purchase order line and an order title (note that the order title is not the inventory instance, but an object in mod-orders that represents the title). Since a purchase order line can have multiple order titles (in the case of “package” order lines) both the POL and Order Title must be specified when linking a serial record to an order line.

A serial record POST body will be like:

{
  "description": "description of the serial, optional",
  "serialStatus": "active",
  "orderLine": {
    "remoteId": "<uuid of POL>",
    "title": "title of serial"
    "titleId": "<uuid of order title>"
  },
  "notes": [
    {
      "note": "repeatable note field"
    },
    {
      "note": "second note"
    },
  ]
}

serialStatus has valid values active, closed and is required

At least one of description or orderLine is required. If orderLine is provided all three of orderLine.remoteId, orderLine.title and orderLine.titleId should be provided (although technically only the remoteId is required, without the other two fields the serial will not function as expected).

the orderLine.remoteId is the UUID of the POL that should be linked
the orderLine.title is a locally stored string which would usually be taken from the order title, but can be any valid string. This displays in the Serial search results
the orderLine.titleId is the UUID of the order title to which the serial should be linked

Publication pattern

A publication pattern is always linked to a serial record. The publication pattern defines everything needed to predict a set of expected pieces/issues of a serial. The prediction aspects of the publication pattern are split into:

One recurrence which defines how often a serial is published and on which days
Zero to many combinations which define any combined issues that are published (note that it is not currently possible to have both combinations and omissions in a single pattern)
Zero to many omissions which defines any issues which are skipped (note that it is not currently possible to have both combinations and omissions in a single pattern)
One templateConfig which in turn contains
- zero to many enumeration rules which define how published pieces/issues are numbered
- zero to many chronology rules which define how published pieces/issues are dated
- a templateString which defines how to generate a display summary for each published piece/issue based on it’s enumeration and chronology rules

Recurrences

A recurrence in the Serials Management module governs the publication frequency rules for a serial. Recurrences are defined with the properties:

timeUnit (day, week, month or year) → the time unit to use for the publication frequency
period (an integer) → the number of time units to be used
issues (an integer) → the number of issues received during the period of time defined by the period and timeUnit
Recurrence rules → rules to calculate on which date an issue is published

So if you can write any frequency in terms of the number of issues per period of time like:

^{<issues> issues per <period> <timeUnit>}

for example:

1 issue per 1 month becomes

^{"timeUnit": {"value": "month"}, "period": 1, "issues": 1}

This flexibility means that for some options, there are multiple ways of expressing the same frequency (e.g. 1 per month, vs 12 per year). In cases where there are multiple options, the decision on which expression of frequency to use should usually be guided by which will give the most concise way of expressing the pattern including the dates/days of publication (see recurrence rules below). For guidance, some common frequencies and suggested recurrence JSON (omitting the recurrence rules which are discussed separately below) are given in this table:

Frequency	MARC frequency code (853$w)	Recurrence JSON	Notes

Frequency	MARC frequency code (853$w)	Recurrence JSON	Notes
Annual (one issue per year)	a	^{"timeUnit": {} ^{"value": "year"} ^}, ^{"period": 1,} ^{"issues": 1}
Bimonthly (one issue per two months)	b	^{"timeUnit": {} ^{"value": "month"} ^}, ^{"period": 2,} ^{"issues": 1}
Semiweekly (two issues per week)	c	^{"timeUnit": {} ^{"value": "week"} ^}, ^{"period": 1,} ^{"issues": 2}
Daily (one issue per day)	d	^{"timeUnit": {} ^{"value": "day"} ^}, ^{"period": 1,} ^{"issues": 2}
Biweekly (one issue per two weeks)	e	^{"timeUnit": {} ^{"value": "week"} ^}, ^{"period": 2,} ^{"issues": 1}
Semiannual (two issues per year)	f	^{"timeUnit": {} ^{"value": "year"} ^}, ^{"period": 1,} ^{"issues": 2}
		^{"timeUnit": {} ^{"value": "month"} ^}, ^{"period": 6,} ^{"issues": 1}	Twice a year and once every six months can both be used to model a semiannual publication
Biennial (one issue per two years)	g	^{"timeUnit": {} ^{"value": "year"} ^}, ^{"period": 2,} ^{"issues": 1}
Triennial (one issue per three years)	h	^{"timeUnit": {} ^{"value": "year"} ^}, ^{"period": 3,} ^{"issues": 1}
Three times a week (three issues per week)	i	^{"timeUnit": {} ^{"value": "week"} ^}, ^{"period": 1,} ^{"issues": 3}
Three times a month (three issues per month)	j	^{"timeUnit": {} ^{"value": "month"} ^}, ^{"period": 1,} ^{"issues": 3}
Monthly (one issue per month)	m	^{"timeUnit": {} ^{"value": "month"} ^}, ^{"period": 1,} ^{"issues": 1}
Quarterly (four issues per year)	q	^{"timeUnit": {} ^{"value": "year"} ^}, ^{"period": 1,} ^{"issues": 4}
		^{"timeUnit": {} ^{"value": "month"} ^}, ^{"period": 3,} ^{"issues": 1}
Semimonthly (two issues per month)	s	^{"timeUnit": {} ^{"value": "month"} ^}, ^{"period": 1,} ^{"issues": 2}
Three times a year (three issues per year)	t	^{"timeUnit": {} ^{"value": "year"} ^}, ^{"period": 1,} ^{"issues": 3}
		^{"timeUnit": {} ^{"value": "month"} ^}, ^{"period": 4,} ^{"issues": 1}
Weekly (one issue per month)	w	^{"timeUnit": {} ^{"value": "week"} ^}, ^{"period": 1,} ^{"issues": 1}

Recurrence Rules

Recurrence rules are used to calculate on which specific days a serial issue will be published. A recurrence like "timeUnit": {"value": "month"}, "period": 1, "issues": 1 tells us there is one issue per month (12 per year), it doesn't specify which day of the month the issue will be published - this is where the recurrence rule is used.

Recurrence rules can have different levels of complexity depending on the recurrence specified. For example if a monthly serial issue is published on the same day of each month, the recurrence is "1 issue per month" and the recurrence rule only has to say which day of the month (1-31) the issue is published. However, if the issue is published on a different day each month, or has a less regular pattern, the recurrence may need to be amended to allow the recurrence rule to be much more specific. The examples below should illustrate this more fully.

Examples tba here...