Patron import from web services

Cicero offers the option to import information about patrons associated with an institution from
selected web services.

Information about pupils and staff is updated periodically with new information, so that pupils, for example, automatically change class (move up) as the institution updates the information in their web service.

The following describes how the import is handled:

1. For each branch, a patron group is created with the branch's name. The patron group is created as a
   patron group under 'All' if it does not already exist.
2. Under Branch, three patron groups are created named respectively ”Pupils”, ”Staff” and ”Left”. In these, patron groups are created based on class information from the info service.
   • The import does not change any patron groups other than those mentioned.
   • The import places staff directly in the Staff group.
   • For pupils, a patron group is created per class. A pupil can be a member of many groups, but by default only the main group is imported.

Cicero matches pupils and staff on UNI-Login, secondarily on CPR number, and finally matches on name and
all address fields. Patrons (pupils) are placed in the groups created based on the information from
the info service. If Cicero cannot find the patron in the system, the patron will be created.

After the import, pupils can thus be found in patron groups of this form:

• All >Brædstrup Skole > Pupils >6b

The first time an import is performed, duplicate patron groups can potentially be created, as the structure from
conversion from the existing system does not necessarily match the structure read
from the patron import web service. The import retains both the original structure and the imported one,
provided they do not overlap. The patrons will belong to both patron groups. If the school is satisfied with the
imported structure, the old patron groups can be deleted.

If several branches have the same institution number, the classes will be created at both branches, and thus
the patrons will be associated with the class at both branches. This typically occurs in connection with administrative
merging of schools.

Configuration of importing patron data from a web service

It is possible to configure which data you want to have imported, via either UNI*C, UC patron import
service, TIETO/IST or by uploading a CSV file. This is done via Admin > General settings > Patron > Import patron rules. The configuration can be set up differently for each individual branch, if needed.

The configuration is made as XML syntax and by default looks as follows:

<ImportLoanerConfiguration>
         <Service>


        </Service>


        <DataToImport>
                  <BirthDate>true</BirthDate>
                  <CPR>true</CPR>
                  <Address>true</Address>
                  <Email>true</Email>
                  <Phone>true</Phone>
                  <AllGroups>false</AllGroups>
                  <Guardian>true</Guardian>

                  </DataToImport>


                 <OverwritePhoneNumbers>false</OverwritePhoneNumbers>
                 <OverwriteEmails>false</OverwriteEmails>
                 <OverwritePickupBranch>true</OverwritePickupBranch>


    <EnableNotificationOnDataUpdate>
                 <SMS>false</SMS>
                 <Email>false</Email>
                 <DigitalPost>false</DigitalPost>
  </EnableNotificationOnDataUpdate>


                <UseCPRasUserId>false</UseCPRasUserId>
                <NotifyNewPatron>false</NotifyNewPatron>
                <SkipEmailIdentifier>false</SkipEmailIdentifier>
                <AutoDeletePatronsWithOutstandings>false</AutoDeletePatronsWithOutstandings>
                <AutoDeleteReservationsOnBranchTransfer>false</AutoDeleteReservationsOnBranchTransfer>


</ImportLoanerConfiguration>

It is important that the text between '< >' is not changed and that only ”true” or
”false” can be specified, depending on whether you want to enable or disable import of the field in question.

• <BirthDate> if this is false, the date of birth is not inserted/updated
• <CPR> if this is set to false, the CPR field will be empty when creating a new patron, and the field
  is not updated for existing patrons. CPR numbers in the imported data will be used to
  match existing patrons regardless of this setting.
• <Address> if this is false, the field is not updated.
• <Email> if this is false, the email address is not inserted/updated.
• <Phone> if this is false, the phone number is not inserted/updated.
• <AllGroups>
  o It is disabled by default (false)
  o For import from UNI*C and TIETO/IST, if the parameter is set to false only
  the main group will be imported. This is typically the pupil's class. If it is set to true, all
  groups associated with a patron from UNI*C or TIETO/IST will be imported. This often includes
  a lot of subject groups.
• <Guardian> this is only relevant for import from UNI*C, TIETO and IST. If this is set to
  true, or is not set, financially responsible persons will be imported for patrons. If it is false,
  they are not imported. Enabled by default.
• <OverwritePhoneNumbers> if this is true, existing phone numbers will be
  overwritten/deleted.
• <OverwriteEmails> if this is true, existing emails will be overwritten/deleted.
• <OverwritePickupBranch> if this is true, the patrons' collection branch will be overwritten.
• <EnableNotificationOnDataUpdate><SMS> if this is true, SMS
  notifications will be enabled for the imported mobile number, if the patron does not already have a mobile number
  for notifications.
• <EnableNotificationOnDataUpdate><Email> if this is true, email
  notifications will be enabled for the imported email, if the patron does not already have an email for notifications.
• <EnableNotificationOnDataUpdate><DigitalPost> if this is true, digital post
  notifications will be enabled for a patron if it is the first time the patron is imported.
• <UseCPRasUserId> if this is true, a Patron ID of the type
  ”Health card” will be created with the patron's CPR number. Provided, however, that the CPR number
  is imported and is present.
• <NotifyNewPatron> if this is true, 'Welcome to new patrons' emails will be sent to
  patrons created by the import.
• <SkipEmailIdentifier> If this is true, patrons' email addresses will not be used as an identifier when importing from Tieto, IST, Schoolsoft or Feide. This is relevant to enable if several patrons have the same email address (which can occur, for example, if pupils are registered with their parents' email addresses), as the import would otherwise fail.
• <AutoDeletePatronsWithOutstandings> If this is true, patrons in the "Left" group will be deleted automatically, even if they have active loans or other outstanding items. Read more under Managing departed students.
• <AutoDeleteReservationsOnBranchTransfer> If this is true, patrons who switch to another school within the same agency will have all their reservations deleted that have a collection branch set to the previous school.

In addition to configuring the various patron import rules, you must also configure which patron import web service to use. Cicero supports the following integrations:

• UNI-Login's Info service (ws17)
• UC patron import service
• Tieto, IST, Schoolsoft, Feide
• CSV files

UNI-Login's Info service (ws17)

If you want to integrate with this service, <UNICImport/> must be added to the <Service> element so that
it will look as follows:

<ImportLoanerConfiguration>
<Service>
<UNICImport/>
</Service>
…
</ImportLoanerConfiguration>

A prerequisite for a patron import using UNI-Login's Info service is an approved data agreement
between KOMBIT or Systematic and the individual school.

The library must approve ”KOMBIT A/S Info service ws17” access to data via https://tilslutning.stil.dk/tilslutning/.

Read more in STIL's documentation or under FBS integration to STIL Infotjenesten.

UC patron import service

If you want to integrate with this service, the following is required in the <Service> element:

<ImportLoanerConfiguration>
           <Service>
                    <UCImport>
                              <ServiceURL>URL</ServiceURL>
                              <UcKortNavn>name</UcKortNavn>
                              <ApiKey>key</ApiKey>
                  </UCImport>
         </Service>
…


</ImportLoanerConfiguration>

• <ServiceURL>: The URL of the UC patron import web service.
• <UcKortNavn>: The short name of the institution.
• <ApiKey>: A shared secret.

Tieto, IST, Schoolsoft, Feide

If you want to integrate with this service, <Import/> must be added to the <Service> element so that
it will look as follows:

<ImportLoanerConfiguration>
           <Service>
                    <Import>
                   <UseImportHierarchy>true/false</UseImportHierarchy>
                   </Import>
          </Service>
…
</ImportLoanerConfiguration>

<UseImportHierarchy>:

Boolean that determines whether Cicero's patron group hierarchy should reflect the group hierarchy from the external data source. This is set to ”False” by default.

It may be relevant to set this to ”True” when several schools use the same library (branch). If
there are several schools under the same branch while the boolean is set to ”False”, it will not be possible to see,
which school the individual class belongs to. If the schools have classes with the same name, they will be
created as one class in Cicero. We therefore recommend setting the boolean to ”True” in these cases, as
this will add a level to the patron group hierarchy, which makes it possible to distinguish the schools from one another.
However, this will mean that all schools get an additional level – not only the schools where there are several schools per
library (branch).

Examples:

False: A patron group hierarchy is created in Cicero as follows:
- All
Branch A
▪ Pupils
• Class A
• Class B
Branch B
▪ Pupils
• Class A
• Class B

True: A patron group hierarchy is created in Cicero as follows:
- All
Branch A
▪ Pupils
• School A
o Class A
o Class B
• School B
o Class A
o Class B
Branch B (School C)
▪ Pupils
• School C
o Class A
o Class B

CSV files

When importing from CSV files, the <Service> element is irrelevant and can therefore be empty:

<ImportLoanerConfiguration>
<Service></Service>
…
</ImportLoanerConfiguration>

Read more about import via CSV file under Patron import.