From bc2f8b4acb9f51429dd983a587733ec1170e67f0 Mon Sep 17 00:00:00 2001 From: Alex Buckley Date: Fri, 23 Jun 2017 16:24:05 +0000 Subject: [PATCH] Bug 17956 - Additional koha service information for end of onboarding tool This template contains information about LDAP and SIP and how to set them up with Koha. In addition to configuring z-targets Test plan: 1. Drop and recreate your Koha database 2. Restart memcached 3. Go through the web installer and onboarding tool and notice after creating the circulation rule the next screen provides a 'Start using Koha' button which when clicked prompts you to enter the administrator account credentials you used to create an account in the onboarding tool 4. Apply patch 5. Repeat steps 1, 2 6. Go through the web installer and onboarding tool (on the final screen in the onboarding tool click on the new 'Learn more about Koha' button) 7. The onboardingstep6.tt screen will appear. Click on LDAP radiobutton and click 'Submit' and further instructions on installing LDAP will appear. 8. Click 'Back' and the screen in step 5 will be displayed 9. Click the 'SIP' radiobutton and click 'Submit; and further instructions on setting up SIP will appear 10. Click 'Back' 11. Click both 'LDAP' and 'SIP' and notice that both the LDAP and SIP information is displayed 12. Click 'Back' and click 'Configure z-targets in Koha' and notice how the staff interface login page appears. 13. Repeat steps 1,2 and 6 14. Click the 'Start using Koha' button 15. Login prompt will appear. Enter the administrator account credentials you used to create an account in the onboarding tool Sponsored-By: Catalyst IT --- installer/onboarding.pl | 14 +- .../prog/en/modules/acqui/.booksellers.tt.swp | Bin 0 -> 16384 bytes .../prog/en/modules/onboarding/onboardingstep5.tt | 15 +- .../prog/en/modules/onboarding/onboardingstep6.tt | 266 +++++++++++++++++++++ 4 files changed, 287 insertions(+), 8 deletions(-) create mode 100644 koha-tmpl/intranet-tmpl/prog/en/modules/acqui/.booksellers.tt.swp create mode 100644 koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep6.tt diff --git a/installer/onboarding.pl b/installer/onboarding.pl index 8b032c9..7732115 100755 --- a/installer/onboarding.pl +++ b/installer/onboarding.pl @@ -2,7 +2,7 @@ # This file is part of Koha. # -# Copyright (C) 2017 Catalyst IT +# Copyright (C) 2017 Alex Buckley Catalyst IT # # Koha is free software; you can redistribute it and/or modify it # under the terms of the GNU General Public License as published by @@ -284,10 +284,19 @@ $template_params->{group_types} = [ }, ]; -if ( $step > 5 ) { +if ( $step > 5 && !($op eq "learnservice")) { $template_params->{all_done} = 1; # If step 5 is complete, we are done! $step = 5; } +elsif ( $step > 5 && $op eq "learnservice" ) { + my $service = $input->param('service'); + my $op = "Learn more"; + $template_params->{op} = $op; + my $LDAP = $input->param('LDAP'); + $template_params->{LDAP} = $LDAP; + my $SIP = $input->param('SIP'); + $template_params->{SIP} = $SIP; +} #Getting the appropriate template to display to the user my ( $template, $loggedinuser ); @@ -310,4 +319,5 @@ $template_params->{itemtypes} = $itemtypes; $template->param(%$template_params); + output_html_with_http_headers $input, $cookie, $template->output; diff --git a/koha-tmpl/intranet-tmpl/prog/en/modules/acqui/.booksellers.tt.swp b/koha-tmpl/intranet-tmpl/prog/en/modules/acqui/.booksellers.tt.swp new file mode 100644 index 0000000000000000000000000000000000000000..65754bbea8b6f31c4d86b080b75984f491787878 GIT binary patch literal 16384 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 TM$UK literal 0 HcmV?d00001 diff --git a/koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep5.tt b/koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep5.tt index dfae544..ddd8ba9 100644 --- a/koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep5.tt +++ b/koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep5.tt @@ -19,12 +19,15 @@

Koha

[% IF all_done %] - -

Web installer › Complete

- [% INCLUDE 'onboarding_messages.inc' %] -

Congratulations you have finished and are ready to use Koha

- Start using Koha - +
+ + +

Web installer › Complete

+ [% INCLUDE 'onboarding_messages.inc' %] +

Congratulations you have finished and are ready to use Koha

+ Start using Koha + +
[% ELSE %]

Web installer › Create a new circulation rule

diff --git a/koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep6.tt b/koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep6.tt new file mode 100644 index 0000000..43b9728 --- /dev/null +++ b/koha-tmpl/intranet-tmpl/prog/en/modules/onboarding/onboardingstep6.tt @@ -0,0 +1,266 @@ +[% INCLUDE 'doc-head-open.inc' %] +Learn about other services +[% IF ( Finish ) %][% END %] +[% INCLUDE 'installer-doc-head-close.inc' %] + + +
+
+
+

KohaOther services Koha supports

+ [% IF ((SIP == "SIP") && (LDAP == "LDAP")) %] +

Setting up LDAP with Koha

+ If your organisation has an existing database of user records that are used for authentication then setting up the LDAP service with Koha is a good idea because all user records would be stored in a single central location.
+ LDAP can be used to log into both the Koha staff interface and OPAC.

+ +

Steps to setup Koha with LDAP

+
    +
  1. In your Linux terminal navigate to the directory containing the koha-conf.xml file. This will be either:

  2. +
      +
    • /etc/koha/sites/<instance-name>/koha-conf.xml
    • +
    • /etc/koha/koha-conf.xml
    • +
    + e.g. cd /etc/koha/sites/kohadev/

    +
  3. Open the koha-conf.xml file as root

  4. + sudo vi koha-conf.xml

    +
  5. Scroll down to the line containing "<useldapserver>0</useldapserver>" and change it to:

  6. + <useldapserver>1</useldapserver>

    +
  7. Write in the following information:

  8. + <ldapserver id="<ldapservername>">
    + <hostname><hostname></hostname>
    + <base>dc=<domaincontroller>,dc=<domaincontroller></base>
    + <user>cn=<username>,dc=<domaincontroller>,dc=<domaincontroller></user>
    + <pass><password></pass>
    + <replicate><either0or1></replicate>
    + <update><either0or1></update>
    + <auth_by_bind><either0or1></auth_by_bind>
    + <anonymous_bind><either0or1></anonymous_bind>
    + <principal_name><principalname></principal_name>
    + <update_password><either0or1></update_password>

    +
    Note: The values in these fields (above) will need to be changed to the appropriate value for your organisation. + Hostname can be either an alphanumeric string or an IP address. If the hostname is an IP address then you can choose to explicitly specify the port number or you can leave it as the default.

    + +
  9. The following fields to write in (called maping fields) are optional. What they do is link the Koha database columns with the columns in your organisations user database.

  10. + e.g. the database column firstname is matched with the LDAP element givename
    + <mapping>
    + <firstname is="givenname" ></firstname>
    + <surname is="sn" ></surname>
    + <address is="postaladdress" ></address>
    + <city is="l" >Athens, OH</city> <!--All users by default will have the city value of Athens, OH-->
    + <zipcode is="postalcode" ></zipcode>
    + <branchcode is="branch" >MAIN</branchcode>
    + <userid is="uid" ></userid>
    + <password is="userpassword" ></password>
    + <email is="mail" ></email>
    + <categorycode is="employeetype" >PT</categorycode>
    + <phone is="telephonenumber"></phone>
    + </mapping>
    + </ldapserver>

    +
    Note: The columns on the left (above) are columns existing in the LDAP server, the values in the middle are columns existing in the Koha database. Whilst any values outside the closing brackets on the right (i.e. Athens, OH) are the default values for these fields when a user is created.

    + Where a LDAP column does not have a equivalent Koha column it is recommended you write in "1" for the Koha column value, although this is totally arbitrary. +
    +
    +

    Example LDAP configurations

    + <useldapserver>1</useldapserver><!-- see C4::Auth_with_ldap for extra configs you must add if you want to turn this on -->
    + <ldapserver id="ldapserver" listenref="ldapserver">
    + <hostname>ldaps://ldap.example.co.nz.au</hostname>
    + <base>ou=employees,dc=compnaya,dc=com,dc=au</base>
    + <user></user>
    + <pass></pass>
    + <auth_by_bind>1</auth_by_bind>
    + <replicate>1</replicate> <!-- add new users from LDAP to Koha database -->
    + <update>0</update> <!-- update existing users in Koha database -->
    + <principal_name>ou=employees,dc=companya,dc=com,dc=au</principal_name>
    + <mapping>
    + <userid is="uid" ></userid>
    + <cardnumber is="uid" ></cardnumber>
    + <email is="mail" ></email>
    + <surname is="sn" ></surname>
    + <firstname is="givenname" ></firstname>
    + <categorycode is="1">EM</categorycode>
    + <branchcode is="1">SYD</branchcode>
    + </mapping>
    + </ldapserver>
    + +

    Learn more about LDAP configurations at:
    + LDAP documentation

    +
+ +

Setting up SIP with Koha

+ If you installed Koha using debian packages then setting up SIP is easy, simply follow these steps:

+ 1. In your Linux terminal write in:
+ sudo koha-enable-sip <instancename>

+ 2. Navigate to the directory containing SIPConfig.xml
+ In your Koha home directory write in:
+ cd /etc/koha/sites/<instancename>

+ 3. Edit your SIPconfig.xml file
+ sudo vi SIPconfig.xml

+ 3.1. Edit the port values in the service sections at the top of the SIPconfig.xml file, making sure that the two port values have the same IP address but different port numbers.

+ 3.2. Enter an account. This account must have the same username and password as an account you have created in the Koha staff interface. Also make sure that the account is set to having 'circulate' permissions only.

+ 3.3. Enter an institution. As with account this institution's ID must match the branchcode of a library created in the Koha staff interface

+ 4. In your Linux terminal start SIP by writing in:
+ sudo koha-start-sip <instancename>

+

Learn how to test SIP at: + Evergreen SIP support


+

Important security notice about using SIP

+ To ensure your SIP traffic (the request and response messages sent between you and the SIP server) are secure you must use a stunnel or VPN. +
+ + +
+ + [% ELSIF (LDAP == "LDAP") %] +

Setting up LDAP with Koha

+ If your organisation has an existing database of user records that are used for authentication then setting up the LDAP service with Koha is a good idea because all user records would be stored in a single central location.
+ LDAP can be used to log into both the Koha staff interface and OPAC.

+ Follow these steps to set up LDAP with Koha:

+
    +
  1. In your Linux terminal navigate to the directory containing the koha-conf.xml file. This will be either:
  2. +
      +
    • /etc/koha/sites/<instance-name>/koha-conf.xml
    • +
    • /etc/koha/koha-conf.xml
    • +
    + cd /etc/koha/sites/kohadev/

    +
  3. Open the koha-conf.xml file as root
  4. + sudo vi koha-conf.xml

    +
  5. Scroll down to the line "<useldapserver>0</useldapserver>" and change it to:

  6. + <useldapserver>1</useldapserver>

    +
  7. Write in the following information:

  8. + <ldapserver id="<ldapservername>">
    + <hostname><hostname></hostname>
    + <base>dc=<domaincontroller>,dc=<domaincontroller></base>
    + <user>cn=<username>,dc=<domaincontroller>,dc=<domaincontroller></user>
    + <pass><password></pass>
    + <replicate><either0or1></replicate>
    + <update><either0or1></update>
    + <auth_by_bind><either0or1></auth_by_bind>
    + <anonymous_bind><either0or1></anonymous_bind>
    + <principal_name><princiapname></principal_name>
    + <update_password><either0or1></update_password>

    + +
    Note: The values in these fields will need to be changed to the appropriate value for your organisation.Hostname can be either an alphanumeric string or an IP address. If the hostname is an IP address then you can choose to explicitly specify the port number or you can leave it as the default. +
    +
    +
  9. The following fields to write in (called maping fields) are optional. What they do is link the Koha database columns with the columns in your organisations user database.

  10. + e.g. the database column firstname is matched with the LDAP element givename
    + <mapping>
    + <firstname is="givenname" ></firstname>
    + <surname is="sn" ></surname>
    + <address is="postaladdress" ></address>
    + <city is="l" >Athens, OH</city><!--All users by default will have the city va lue of Athens, OH-->
    + <zipcode is="postalcode" ></zipcode>
    + <branchcode is="branch" >MAIN</branchcode>
    + <userid is="uid" ></userid>
    + <password is="userpassword" ></password>
    + <email is="mail" ></email>
    + <categorycode is="employeetype" >PT</categorycode>
    + <phone is="telephonenumber"></phone>
    + </mapping>
    + <ldapserver>

    + +
    Note: The columns on the left (above) are columns existing in the LDAP server, the values in the middle are columns existing in the Koha database. Whilst any values outside the closing brackets on the right (i.e. Athens, OH) are the default values for these fields when a user is created.

    + Where a LDAP column does not have a equivalent Koha column it is recommended you write in "1" for the Koha column value, although this is totally arbitrary. +
    +
    + +

    Example LDAP configurations

    + <useldapserver>1</useldapserver><see C4::Auth_with_ldap for extra configs you must add if you want to turn this on -->
    + <ldapserver id="ldapserver" listenref="ldapserver">
    + <hostname>ldaps://ldap.example.co.nz.au</hostname>
    + <base>ou=employees,dc=compnaya,dc=com,dc=au</base>
    + <user></user>
    + <pass></pass>
    + <auth_by_bind>1</auth_by_bind>
    + <replicate>1</replicate> <!-- add new users from LDAP to Koha database -->
    + <update>0</update> <!-- update existing users in Koha database -->
    + <principal_name>ou=employees,dc=companya,dc=com,dc=au</principal_name>
    + <mapping>
    + <userid is="uid" ></userid>
    + <cardnumber is="uid" ></cardnumber>
    + <email is="mail" ></email>
    + <surname is="sn" ></surname>
    + <firstname is="givenname" ></firstname>
    + <categorycode is="1">EM</categorycode>
    + <branchcode is="1">SYD</branchcode>
    + </mapping>
    + </ldapserver>
    + +
+

Learn more about LDAP configurations at:
+ LDAP documentation

+
+ + +
+ + [% ELSIF (SIP == "SIP") %] +

Setting up SIP2 with Koha

+ If you installed Koha using debain packages then setting up SIP2 is easy, simply follow these steps:

+ 1. In your Linux terminal write in:
+ sudo koha-enable-sip <instancename>

+ 2. Navigate to the directory containing SIPConfig.xml
+ In your Koha home directory write in:
+ cd /etc/koha/sites/<instancename>

+ 3. Edit your SIPconfig.xml file
+ sudo vi SIPconfig.xml

+ 3.1. Edit the port values in the service sections at the top of the SIPconfig.xml file, making sure that the two port values have the same IP address but different port numbers.

+ 3.2. Enter an account. This account must have the same username and password as an account you have created in the Koha staff interface. Also make sure that the account is set to having 'circulate' permissions only.

+ 3.3. Enter an institution. As with account this institution's ID must match the branchcode of a library created in the Koha staff interface

+ 4. In your Linux terminal start SIP2 by writing in:
+ sudo koha-start-sip <instancename>

+

Learn how to test SIP at: + Evergreen SIP support


+

Important security notice about using SIP2

+ To ensure your SIP2 traffic (the request and response messages sent between you and the SIP2 server) are secure you must use a stunnel or VPN. +

+
+ + +
+ + [% ELSIF op == "Learn more" %] + Koha supports the integration of different library services with it.
+

LDAP user authentication

+ LDAP (Lightweight Directory Access Protocol) can be used to authenticate (login/logout) users. If your organisation has an existing authenication system this can be integrated with the Koha ILS, and so when users enter their credentials into Koha their username and password as compared against the user records in your existing user database to find a match.
+

SIP2 communication protocol between self checkout machines and server

+ SIP2 (Session Initiation Protocol) is a communication protocol used between ACS (Automated Circulation System in this case the Koha server) and SC (Self Checkout machines). If your library/institution has self checkout machines to checkin/checkout items then you will need to configure Koha to use SIP.
+

z-targets

+ Z-targets (also known as z39.50 servers) speed up the library cataloging process because you can query these servers for a specific MARC record (bibliographic record) and then import the record if a match is found saving you having to manually enter the bibliographic information. These servers are run by other libraries and institutions around the world, for example the Library of Congress.

+
+
+ + +

Does your institution use SIP2, LDAP, or both?

+
+ Choose the service +
+ + +
+
+ + +
+
+

+ Configure z-targets in Koha +
+
+ + [% END %] + + [% IF (existingztargets == 0) %] +

Configure z-targets

+ What are z-targets?
+ Z-targets (also known as z39.50 servers) speed up the library cataloging process because you can query these servers for a specific MARC record (bibliographic record) and then import the record if a match is found saving you having to manually enter the bibliographic information. These servers are run by other libraries and institutions around the world, for example the Library of Congress.

+ Login to Koha and configure a z-target
+
+

+
+ [% END %] +
+ Start using Koha +
+
+
+ -- 2.1.4