Axiell Collections
Total Page：16
File Type：pdf, Size：1020Kb
Axiell Collections Installation and configuration Axiell ALM Netherlands BV
Copyright © 2017 Axiell ALM Netherlands BV® All rights reserved. Adlib® is a product of Axiell ALM Netherlands BV® The information in this document is subject to change without notice and should not be construed as a commitment by Axiell ALM Nether- lands BV. Axiell assumes no responsibility for any errors that may ap- pear in this document. The software described in this document is fur- nished under a licence and may be used or copied only in accordance with the terms of such a licence. While making every effort to ensure the accuracy of this document, products are continually being im- proved. As a result of continuous improvements, later versions of the products may vary from those described here. Under no circumstances may this document be regarded as a part of any contractual obligation to supply software, or as a definitive product description. CONTENTS
1 Requirements 1 2 Installing Axiell Collections 7 Access rights 16 Login 16 3 Updating your Adlib application 17 Step 1: create a backup of your Adlib files 17 Step 2: run the ValidateDatabase tool 17 Step 3 (optional): clean up your data 17 Step 4 (for old applications): run ConvertInternalLinks 18 Step 5: convert your output formats 19 Step 6 (optional): set up Change locations procedure 22 Step 7 (optional): set up new Collections functionality 22 4 Application configuration options 23 4.1 Adding geographical maps functionality 23 4.2 Setting up the Related records view 27 4.3 Adding a simple search option 33 4.4 Adding a bulk insert option 35 4.5 Adding the Change locations procedure 37 4.6 Adding a location context column to the link screen 43 4.7 How to include original linked file names 45 4.8 Setting up connect entities 47 4.9 Implementing pseudonyms 49 4.10 Creating output formats for Collections 52 Creating a .docx Word template for Collections 56 Naming conventions for templates 58 Creating standard letters without tables 58 Printing data from a repeated field group in a list 60 Printing data from several records in a list 60 Printing images 62 Printing barcodes 64 Printing multilingual data via Word templates 65 Summary of supported parameters 68 Setting up an output format in Designer 69 Appendix A 73 1 Requirements
Minimally Windows Server 2008 or Windows 7, within an Active Directory domain*, with at least 100MB free disk space. Some requirements differ depending on whether you are about to start using Axiell Collections in combination with Adlib or Calm: - Adlib: an Adlib application (with a subfolder \data). A further re- quirement is that the application data directory is actually access- ible. If the application resides locally on a server, this accessibility is in principle not a problem. However, should it be located on a different server, then you’ll have to check its access rights. - Calm: a Calm application version 10.0.2 or higher. We recom- mend that security is enabled in the Admin program; otherwise, anybody with access to the web server could view or edit data. Ports to the Calm server have to be open through the firewall (as with CalmView) to allow users to access Collections. HTTP server software must be installed on the server on which the web application will be placed, such as IIS 7.0 for Windows Server 2008 or IIS 8.5 for Windows Server 2012 R2. For the required Windows versions, these services are probably already available but might still have to be enabled by setting the IIS Management console and Management service options for the web server.
1 To do so, open the Server Manager and on the Dashboard click the Add roles and features option. Then under Server Roles, look up the relevant Web Server > Management tools options and mark them if necessary. In Windows 10 you would do this via the Windows Features dialog (Control Panel > Programs > Programs and Features > Turn Windows features on or off).
Further make sure that (under Features) for the .NET Framework the WCF Services > HTTP Activation option is marked.
2 In Windows 10 you would find it in the Windows Features dialog.
The IIS Web Deploy extension should have been installed on the IIS Server. In IIS you can check whether the extension is already available or not, by right-clicking the Default Web Site to open the pop-up menu: if the Deploy option is present in the options list, the extension is present. If not, download and install the latest version (choose the 64-bit version for 64-bit Windows) from https://www.microsoft.com/en-us/search/result.aspx?q=web+de- ploy. Restart IIS after installation and check if the Deploy option is present yet. (If you’ve marked the web server Management Service option (see previous requirement) after installing Web deploy, you may have to run the Web deploy installation again and choose the Repair installation option. Restart IIS and check again.)
3 If the Deploy option still doesn’t become available in the pop-up menu, then deinstall the extension you just installed and see the procedure in Appendix A. You can deploy Collections in any folder, but by default it will be deployed in C:\inetpub\wwwroot with the web application name you provide during the deployment. Before you can start deploy- ment, do make sure you have full access rights to the desired tar- get folder, otherwise the application cannot be deployed and you’ll get an error message during deployment. The Microsoft .NET Framework version 4.0 (or higher) must be in- stalled on the server, yet only when IIS has already been installed (with the latest security updates), otherwise some important fea- tures of ASP.NET will be missing from the installation. So on a new server, always install IIS before you install the .NET Frame- work. For information about the .NET Framework, see: https://msdn.microsoft.com/en-us/vstudio/aa496123. (If the .NET Framework still has to be installed, then please take into account that the web server might need rebooting after this installation.) On IIS 7, ASP.NET must operate in integrated mode (which is the default configuration). The application pool which we will create for the Axiell Collections application, must run in this mode.
4 Running Axiell Collections requires a browser: Chrome, Firefox, Safari or Edge. Some requirements differ depending on whether you are about to start using Axiell Collections in combination with Adlib or Calm: - Adlib: if Active Directory authentication will be used for access to the database, instead of SQL Server authentication, then the application pool must be configured to use an account which has access to the SQL Server. The easiest way to set up access rights for multiple users, is if you use SQL Server authentication and set the process model identity of your application pool to NetworkService. Then users can log in with their Windows user name, but on SQL database level all users will have access via one and the same SQL Server user name. Via the Adlib internal access rights mechanism (as can be set up through Adlib Designer), individual users can still be as- signed differentiated access rights, but the one SQL user does have to have database owner rights because some user actions cause the creation of new SQL database tables (like the first time a user creates a saved search in a data source). - Calm:
* Although not recommended, Axiell Collections, the Adlib application and the database server can also be installed in a peer-to-peer net- work, within a workgroup, in which case each computer/server in the workgroup needs to have its own (matching) user accounts and secur- ity control to be able to share their resources. In this case, the Collec- tions web application folder and the Adlib application folders require sharing and the anonymous IIS_USR user needs to have read-only ac- cess rights to these folders. Another requirement is that in IIS the An- onymous Authentication for the Collections web application needs to be set to Application pool identity (instead of Specific user) to allow the user normal access to the web application: without this setting the login screen will be presented on a white page without proper layout (see screenshot below).
5 2 Installing Axiell Collections
1. You have received the Axiell Collections deployment package (Axiell.Alm.MVC.KendoSPA.zip) from the Axiell ALM support desk. Place this file in a folder on the server you intend to use for Axiell Collections. Later during this procedure, the physical files of the web application will be installed in this folder if desired (name it appropriately in that case) or in C:\inetpub\wwwroot, depending on what you do in step 7. 2. Open IIS on the server and create a new .Net v4.0 application pool, AxiellCollectionsPool for example, and leave the default basic settings (Integrated mode) as they are.
In the Advanced settings of the new application pool, either set the (Process Model) Identity to use the ApplicationPoolIdentity (Built-in account) or a custom (usually a general) Active Directory account, depending on your SQL server/network access rights. To increase performance on startup of Collections and to avoid having to log in again after leaving Collections idle for some time, also set the (Process model) Idle time-out (minutes) and (Recyc- ling) Regular time interval (minutes) to 0: this avoids unnecessary recycling of the application pool.
6 3. We recommend using HTTPS as the data transfer protocol. You would first need to acquire an SSL certificate from your local certi- fication organisation and install it on the server. (In IIS you can find any installed certificates when you select the server in the left window pane and double-click the Centralized certificates icon.) Right-click your default website in IIS and select Edit bindings in the pop-up menu. In the window that opens, click Add, select the https binding type and then click the Select button to be able to select your SSL certificate. Next you’ll have to redirect all HTTP re- quests to HTTPS, for example using URL Rewrite, a plugin for IIS. Information about how to set up a redirect can be found else- where: here for example. 4. In IIS, add a new application called Collections, underneath the Default Web Site and assign it your new application pool.
In the Add application window, use the Test Settings button to check whether a connection can actually be made. 5. Underneath the Default Web Site, your new application is now vis- ible. Right-click the Default Web Site (if you’d like the physical files to be installed in C:\inetpub\wwwroot\
7
path (in which case the physical files will be installed in the folder containing the deployment package) or leave the suggested folder name in the entry field (or type a new one) to deploy the applica- tion there (in which case the physical files will be installed in C:\inetpub\wwwroot\
9. In the Overwrite Existing Files step, choose the first option if you already have an Axiell Collections installation in place on that loca- tion, which you’d only like to upgrade: any custom settings in \App_Data\settings.xml remain as they were. Conversely, select the second option if this is a fresh installation and any files and folders in the target location can be deleted.
10. Click Next to start the actual deployment now. After installation has finished, the wizard should report a successful installation. Click Finish.
8 11. In IIS, right-click your Axiell Collections application and select Ex- plore in the pop-up menu to open the installation folder in Windows Explorer. Open the \App_Data folder. 12. In the \App_Data folder you’ll have to create a settings.xml file if you’ve installed Axiell Collections for the first time. To do this, just copy and paste the settings.example.xml file and rename the copy to settings.xml. The settings.xml file will have to contain some custom settings to tell the web application where to look for your Adlib application, amongst others. 13. This step in the installation procedure differs depending on wheth- er you are about to start using Axiell Collections in combination with Adlib or Calm:
- Adlib: open settings.xml in an appropriate editor (like Notepad+ + for example). In case of a default, singular Adlib installation where all users use the same application, you can leave
9
The optional Scope attribute for the
CacheScripts (set to false) is an optional setting for develop- ment purposes, which enables the reloading of an adapl bin file each and every time it is called, so that recycling of the applica- tion pool isn't required after making changes to the adapl. Leave out this setting to increase performance.
Path: the Value for the "SQL" session manager should be set to the actual, full path to your Adlib application folder. You can’t use drive letters for shares: use the original path to the server in a format like: \\myserver\adlib\xplus. Instead of setting the path to a specific Adlib application folder (like \xplus), you can also set it to the Adlib software root folder (containing multiple application folders, like \xplus, \library, \museum, etc.) if you’d like to offer the user a choice of applications to log on to.
Preload: the Value indicates the level at which to pre-load parts
10 of the web application to reduce delays for users who are the first to log on to Collections:it concerns delays before the login dialog is displayed, before the Select database dialog and before a record is displayed after performing a search. You can assign one of four values: None (pre-load is switched off), Basic (pre-loads only data source info), More (pre-loads basic schema info and com- monly-used objects) and Full (pre-loads everything, including adapls if required). For values other than None, Collections will load the relevant schema objects when the application pool starts, so delays will be concentrated before the login dialog is opened for the first time during a session. Note that the application pool user must have at least read access rights to the application for pre- loading to work. Enabling this option isn’t always the best choice, like for a large multi-tenancy system. It increases baseline server resource us- age.
DomainController and DomainContainer: these settings are useful for tightening up security for local demo installation that are not connected to the domain. If a user has locked down their default Active Directory configuration, we need to be able to query non-default domain controllers and containers, for which you can use these settings.
DomainUsersOnly: with this option set to false, if a Collections user can't authenticate against Active Directory then Collections will automatically authenticate against machine accounts on the Collections server. Although the account will be on the Collections server (which should be secure), the behaviour may not be as ex- pected and allows access to Collections that can't be controlled through Active Directory. Use this setting (Value="false") for local demos that are disconnected from the domain, otherwise you can’t log in. By default, the option is set to true to allow only domain users to log in, which is the more secure choice.
Multi-tenancy In most cases you’ll be using a singular Adlib application, which makes the above settings all you need. In the case of an enter- prise multi-tenancy situation however (multiple instances of Col- lections running under the same web application), where users from different branches are allowed access to only one (or some) of many different applications (each with their own user list and access rights), the current session manager should be set to "Multi". Within this SessionManager definition you must then
11
list all applicable Active Directory groups (without domain) as Key attribute with an accompanying, appropriate id as Value attribute. For example:
The ids for the different user groups that you’ve now specified must then be defined as separate session managers too, so that any user can be associated with the appropriate application(s) in Axiell Collections. So, for example:
Note that the application folder paths you set for a multi-tenancy configuration must always point to a specific Adlib application folder, like \xplus for example: you cannot point it to the Adlib software root folder to offer the user a choice of applications. This is because a user must have logged in first, for Collections to be able to determine which applications can be accessed by the user (so a list of available applications cannot be offered beforehand). If a root folder is specified anyway, the multi-tenancy session manager will automatically pick the first matching application in the referenced session manager.
- Calm: open settings.xml in an appropriate editor (like Notepad+ + for example). In case of a default, singular Calm installation where all users use the same application, change
with the administrator attribute and drum in
In most cases you’ll be using a singular Calm application, which makes the above settings all you need. In the case of an enter- prise multi tenancy situation however, where users from different branches are allowed access to only one (or some) of many differ- ent applications (each with their own user list and access rights), the current session manager should be set to "Multi". Within this SessionManager definition you must then list all applicable Active Directory groups (without domain) as Key attribute with an accompanying, appropriate id as Value attribute. For example:
The ids for the different user groups that you’ve now specified must then be defined as separate session managers too, so that any user can be associated with the appropriate application(s) in Axiell Collections. So, for example:
14 15. In IIS, right-click your new application pool and choose Recycle in the pop-up menu.
Access rights - Adlib: Adlib applications must be secured (typically on database and field level) using the Adlib access rights mechanism to restrict unau- thorized users from access to certain or all data, because with a sin- gular Axiell Collections installation any domain user can in principle log on. So typically you would set applicable access right Read, Write or Full for specific authorized users or user groups, and assign None access right to $REST per database to keep out all other users. When you’ve configured your application for multi-tenancy, users can only log on to their designated application if they are a member of the proper Active Directory group, so typically you would populate these AD groups only with people that have at least read access to some or all of the databases, and further specify their access rights with the Adlib access rights mechanism. - Calm: User access is controlled using the Calm Admin program. Se- curity must be enabled in the Admin program. If you are using Windows Active Directory logins to access Calm, any users that you would like to be able to access Collections must appear in or be added to the User tab of the Security dialogue box in the Admin program.
Login The installation is now complete. You can start using Axiell Collections by entering the proper URL in your browser. (An Axiell Collections ap- plication installed locally on your PC can be accessed in your browser by entering http://localhost/ in front of your web application name, for example: http://localhost/collections.) In most cases you’ll subsequently have to log in using your own Windows login name and password. (If there’s no Active Directory on the server on which you’ve installed and access your (singular) Collections web application, you can log in with your Windows credentials, but you’ll have to specify the name of the relevant server or pc in front of your user name, like: mymachine\user.) If during login you get a server error stating that the system cannot contact a domain controller to service te authentication request, it means Axiell Collections has no access to the server which stores all network user names and passwords (aka the domain controller). So check whether the domain controller is accessible from the server on which Axiell Collections was installed.
15 3 Updating your Adlib application
If you plan on running Axiell Collections on an existing Adlib applica- tion (4.5.1 or older), you’ll have to make that application Collection- s-ready first.
Step 1: create a backup of your Adlib files Before you start changing your application or database structures, it’s always wise to create a backup of all your Adlib files. You’ll have a working application to fall back on if anything should go wrong.
Step 2: run the ValidateDatabase tool Before you start using Axiell Collections - whether it is to replace or to supplement Adlib for Windows – you should make sure your Adlib ap- plication and database structure are in good shape: to ensure the fu- ture integrity and safety of your data, Axiell Collections is not as for- giving towards some database structure imperfections as Adlib for Windows has always been. Checking and fixing your database structures for this purpose is fairly easy: you need to run the ValidateDatabase.exe tool. The goal of the tool is to check one or more Adlib databases for any field tags that have not been defined in the data dictionary (your .inf database struc- ture files), report on them and add generic field definitions for those tags to the relevant .inf’s. (The tool works on SQL databases only.) So please download the tool here, read the ValidateDatabase chapter in the Database integrity tools guide which you can download here and run the tool for all your databases: use the fix option to add any missing generic field definitions.
Step 3 (optional): clean up your data Cleaning up your data is something you can always do, but the trans- fer to Axiell Collections might be an extra motivation. There are sever- al Adlib tools available to help you with that process, available from our helpdesk, which should be used in the order listed below to get the best results: 1. RemoveTagsFromData - The purpose of the RemoveTagsFrom- Data.exe tool is to remove tags and their content from your records in one or more Adlib SQL databases. After you’ve run the ValidateDatabase tool, you may find several new provisional fields in your .infs. These might very well be fields that you actively use: screen fields that were never officially registered in the .inf before,
16 for example. These fields you should definitly keep. But of some other newly registered tags you may find that the data they con- tain is garbage (which may have entered your records accidentally during an import or an adapl procedure, for example) and those tags and their data you’ll probably want to remove from your database as efficiently as possible. Then, RemoveTagsFromData is the perfect tool for this job. For more information, see the Re- moveTagsFromDatabase chapter in the Database integrity tools guide which you can download here. After removing a tag from a database, you can remove the rele- vant provisional field definition from the .inf manually, since it no longer serves a purpose. 2. IndexCheck - The purpose of the command line IndexCheck tool is to check whether indexes in your databases are correct, by reading all records again and comparing the current contents of the index to what is supposed to be indexed. If wrong keys appear in the current index, or if values from records are still missing in it, IndexCheck can automatically perform repairs to yield a correct index. See the IndexCheck chapter in the Database integrity tools guide, for more information about this tool. 3. LinkRefCheck - The purpose of the command line LinkRefCheck tool is to make sure that the reference in the link reference tag of linked fields in your SQL database points to an existing linked record, and that no value is stored in the linked field itself. It also empties any accidentally stored merged-in fields, because merged-in fields shouldn’t be stored in the database either. If a correct link reference is present (pointing to an existing record in the linked database), and the linked field value itself and any merged-in field values do not appear in the stored record, then things are how they should be, so nothing is changed. Different erroneous situations for a linked field can in principle exist though, which will all be fixed by LinkRefCheck. For more information, see the LinkRefCheck chapter in the Database integrity tools guide.
Step 4 (for old applications): run ConvertInternalLinks The purpose of the ConvertInternalLinks tool is to convert both the structure and contents of fields internally linked on value (as was the case in Adlib model applications older than version 4.2) in one or more tables in your Adlib SQL database to fields internally linked on reference. So if you have an Adlib application 4.2 or higher, please skip step 4: your internally linked fields are already linked on refer- ence.
17
Step 5: convert your output formats Printing from Axiell Collections is different from Adlib for Windows. The bad news is that Collections does not support output adapls using print and output statements to print stuff, nor does it support Word template output formats with the .dot and .dotx extension. The good news is that is Collections does support Word templates with the .docx extension, it supports output adapls using the wordcreate- document function (to print from a .docx template), it supports output formats which have been specified as a combination of an adapl and a .docx template, and it also supports XSLT stylesheets as output for- mats. By the way, the new .docx format is also supported by Adlib for Windows 7.5 or higher. Word templates We already made a couple of standard Word templates in the new .docx format, to print object data, but any Word templates you may have created yourself in the past must now be converted to the new format if you’d like to have them in Axiell Collections. Currently there is no automated procedure to do this, so you must do it manual- ly. Fortunately this is not difficult at all in most cases, nor very time consuming. And you don’t need to actually change the references to your Word templates in your application structure (.pbk): Collections will automatically look for .docx templates with the same name as the .dot(x) templates already set up as output formats in the past. Please see chapter 4.8 for more information about converting your ex- isting Word templates and how to get the new standard Word tem- plates. Print adapls using wordcreatedocument In the Transport/Despatch and Incoming loans and Outgoing loans data sources, there are a number of Template checkboxes which, once clicked, generate a Word document, a request or freight letter for ex- ample, in the selected language, after which the path to the created document is automatically being registered in the Digital document field.
18 This is handled by two after-field adapls: loanproc.ada/bin and tran- proc.ada/bin. The adapls use the wordcreatedocument function and the yesno function. Instead of the old .dot templates, the wordcre- atedocument function should now address .docx templates while the yesno function doesn’t really work in Collections and just always re- turns 1 (as if the user replied Yes to the question). So the adapls need to be adapted to deal with this and all called templates need to be converted to the new .docx format, before you can use these check- boxes in Axiell Collections. If you are using a model application 4.5.1, running on Adlib for Windows 7.5 or higher or in Axiell Collections, you can just download the new model templates and adapls here and move the adapls from the zip file to your Adlib \adapls folder and move the templates to your Worddoc\templates folder. However, if you had adjusted any of the following templates in the past, by adding your institution name or logo or by altering the fixed texts, you are probably better off just us- ing the adapls from the zip file and converting your templates your- self: condition#.dot, condition-in#.dot, condition-objin#.dot, con- tract#.dot, despatch#.dot, entry#.dot, ownerrequest#.dot, renewal#.dot, renewal-out#.dot, request#.dot, request-out#.dot and reviewrequest#.dot. Converting these particular templates yourself, also if you’re using an older application version, usually only requires opening them in Word and saving them under the same name but as a .docx file. Users of older applications could adjust their loanproc.ada/bin and tranproc.ada/bin themselves, given the following information. Please do not just copy the code: first check if in how far it applies to your application and change what needs to be changed. Aspects of loan- proc.ada/bin 4.5.1 and tranproc.ada/bin 4.5.1 that have changed:
The following variables have been added to the variables declara- tion: text templatename[50] text strippedtime[6], fulltime[8] integer templatenamelength The partial string ‘.doc’ was removed from the string behind doc- name = everywhere in the code. For example: docname = '_re- quest.doc' became docname = '_request'.
Sub routine 500 and 501 in loanproc.ada were changed to: 500 /* Create Word document templatename = enumval$ (!templatetag[occ], !templatetag, -1) if (right$(templatename,3) = 'dot') { templatenamelength = (len(templatename) - 3) templatename = left$(templatename, templatenamelength) + ~
19
'docx' } if (right$(templatename,4) = 'dotx') { templatenamelength = (len(templatename) - 4) templatename = left$(templatename, templatenamelength) + ~ 'docx' } result = WordCreateDocument (template_path + templatename, ! docreftag[occ], 1) if (result <> 0) { errorm 'Error creating Word document ' + ~ !docreftag[occ] + '; code = ' + result !docreftag[occ] = '' } else { !docdatetag[occ] = date$(8) } return
501 /* Create Word document reference: document_path + /* loan number + docname + date + time (without colons) /* + .doc
fulltime = time$(1) strippedtime = left$(fulltime,2) + ~ mid$(fulltime,4,2) + right$(fulltime,2) !docreftag[occ] = document_path + !numbertag + ~ docname + '_' + date$(8) + '_' + strippedtime + '.doc' return
Sub routine 500 in tranproc.ada was changed to:
500 /* Create Word document fulltime = time$(1) strippedtime = left$(fulltime,2) + ~ mid$(fulltime,4,2) + right$(fulltime,2) !docreftag[occ] = destination_path + !numbertag + ~ docname + '_' + date$(8) + '_' + strippedtime + '.doc' templatename = enumval$ (!templatetag[occ], !templatetag, -1) if (right$(templatename,3) = 'dot') { templatenamelength = (len(templatename) - 3) templatename = left$(templatename, templatenamelength) + ~ 'docx' } if (right$(templatename,4) = 'dotx') { templatenamelength = (len(templatename) - 4) templatename = left$(templatename, templatenamelength) + ~ 'docx' } result = WordCreateDocument (template_path + templatename, ! docreftag[occ], 1) if (result <> 0) { errorm 'Error creating Word document ' + ~ !docreftag[occ] + '; code = ' + result !docreftag[occ] = ''
20 } return For the relevant fields, the yesno function in loanproc.ada can present the following questions to users in Adlib for Windows, while in Collec- tions they are skipped and assumed confirmed: Do you want to add the objects (excl. refused/withdrawn) to the exhibition record? Do you want to create a Despatch record for these objects (excl. refused/withdrawn)? Do you want to create an entry record for these objects (excl. re- fused/withdrawn)? This Word document has been ceated before. Do you still want to create a new document? The changes in sub routines 500 and 501 are meant to address the fourth question: to prevent earlier created Word documents from be- ing overwritten by default in Axiell Collections. The sub routine does overwrite the contents of the field but the document it creates will get a unique name so that the old document won’t be overwritten. For the relevant field, the yesno function in tranproc.ada can present the following question to users in Adlib for Windows, while in Collec- tions it is skipped and assumed confirmed: Do you want to update the current location for the linked objects with the location you have entered here? Note: If you have not entered a date and/or time here, the current date/time will be used.
Step 6 (optional): set up the Change locations procedure Contrary to the Change locations procedure in Adlib for Windows, Ax- iell Collections uses a customizable setup. So if you’d like to have this functionality in Collections, you’ll have to set it up first. We’ve already done some of that work for you, so you won’t have to start from scratch. The setup needs to be done with Adlib Designer 7.5 or higher, which means that you’ll have to update your Adlib for Windows exe- cutables to that version as well if you keep on using Adlib for Windows. Please see chapter 4.5 for more information.
Step 7 (optional): set up new Collections functionality Axiell Collections offers quite some new functionality, compared to Adlib for Windows, such as the geographical maps functionality, a re- lated records view and a bulk insert option. This is optional, additional
21
functionality which needs to be set up first, simply because it’s highly customizable. Please see the relevant Application configuration op- tions chapters below, for more information.
22 4 Application configuration options
The Axiell Collections application (the data sources it offers, its screen tabs, the available database fields, etc.) which runs on an Adlib SQL database, uses Adlib definition files just like the Adlib for Windows software: .inf files for Adlib database specifications, a .pbk file for the application definition and .fmt files containing screen layout specifica- tions, for example. Therefore the application is highly configurable us- ing Adlib Designer. Some functionality in Axiell Collections has no counterpart in Adlib for Windows and has to be set up explicitly if you’d like to be able to use it in Collections.
4.1 Adding geographical maps functionality Axiell Collections optionally offers geographical map functionality. If implemented for a database, a Geographical map view is available (next to the Record editor, the Result set and the Media viewer and so on).
23
The view is meant to display locations (as registered in different fields in your records) on a world map for a quick visual overview. You can use it to easily track down main locations of storage or the geographi- cal distribution of production places of a certain record selection or the range of content subjects of objects manufactured by a single creator, for example. Also, the Find data for the field dialog for linked geographical place fields will display an extra Geographical map tab which allows you to enter data into the field by selecting a place on the map.
This functionality is not present in the model Axiell Collections applica- tions prior to version 4.5.2, but any field which contains geographical places can be set up for the geographical map functionality, by mak- ing it a so-called "geolocation" designated field. Databases which do not have such special fields won’t offer the maps functionality.
Creating geolocation fields In the Application browser of Adlib Designer, proceed as follows to create geolocation fields: on the Field properties tab of field definitions in the data dictionary you'll encounter a Data type called Geo location. The intention is not to create any new fields with this data type but to change the data type of one or more existing fields (linked or not) that contain geographical names, (mostly from data type Text) to Geo location if you'd like those fields to have the validation by geographi- cal map (if it concerns a linked field) and if you want those fields to be selectable in the Geographical map view of Axiell Collections. In normal (adlwin.exe) Adlib for Windows applications, setting the data type of a field to Geo location will have no effect.
24 An example would be the production.place field in the collect.inf database structure. If you make it a geo location field by changing its field definition (no other settings required), the Geographical map view in Axiell Collections allows the user to show the production places of a selection of records as coloured markers on a geographical map which can be zoomed in or out and scrolled in all directions.
Setting up a caching database for geographical places To improve map display performance and to not overload the map provider with too much requests, you can (optionally, but still recom- mended) configure a SQL database to contain geographical location names and coordinates that were automatically marked on the map once before for selected fields in displayed records. This database doesn’t necessarily need to be on the same server as Axiell Collections and it can be shared by multiple applications run by Axiell Collections. Just create a new database in SQL Server like you would normally do for Adlib (see chapter 3.1 in the general Adlib installation guide). You 25
won’t need to create any tables manually: Axiell Collections will auto- matically do that for you the first time the map functionality is used. In Settings.xml, (in your Collections\App_Data folder), underneath the
4.2 Setting up the Related records view The optional Related records view in Axiell Collections provides an al- ternate overview of all linked records in one or more linked fields, grouped per linked data source, while in the linked data source it pro- vides an overview of all records in the first mentioned data source linking to the current record.
Step 1: choose a limited set of linked fields The Related records view is only visible in a data source if at least one (single-sided or reversely) linked field from or to the underlying data- base has been set up for this view. After configuration, the actually displayed relationship is only valid for the specifically set up linked field. So apart from the work involved in configuring linked fields as “relations”, it is good to only apply this functionality to a limited list of fields, otherwise it will become difficult for the user to select the rela-
27
tion(s) he or she would like to see in the view: the overview will be lost. So when you pick linked fields, think about which relations users would like to see: if in Persons and institutions, users would like to see an overview of all objects linking to the currently displayed name record from within the Creator field in Collect, then pick the creator field; if in Locations, users would like an overview of all objects linking to that location from within the Current location field, then pick that field. It doesn’t matter if the linked fields you choose are single-sided linked fields, from Collect to People or Thesau for example, or re- versely linked like between Collect and Loans. In principle, the relat- ed-records functionality requires only a single-sided setup to display both a forward relation in the current data source (links from the cur- rent record to linked records) for the database containing the linked field, and to display a reverse relation in the data source(s) on the other end (links from the database containing the linked field, to the current record). However, for reversely linked fields you typically only specify a forward relation for both reversely linked fields. So relations for single-sided linked fields and reversely linked fields must be imple- mented differently, but don’t let that influence your choice of fields.
Step 2a: configure your selection of single-sided linked fields For a single-sided linked field like creator in Collect you configure re- lations as follows:
28 1. In the Relation texts box on the User interface texts properties tab of the linked field, creator in this example, you specify the for- ward relation label in as many interface languages as are available in your Axiell Collections application. You can use a text like This record > Persons and institutions or This record > cre- ators to indicate that underneath this label the user will find a list of links from the current object record (the Creator field) to name records. 2. In the Reverse relation texts box on the same tab, specify the re- verse relation label that will be visible in Persons and institutions. You can use a text like Objects > this record or Objects (creators) > this record to indicate that underneath this label the user will find a list of links from the Creator field in object records to the current name record. Additionally you can use the {0} system variable to have Axiell Collections insert the target data source name in between brackets. This is mostly useful for the reverse relation text of a single-sided linked field, because when you use the Related records view in a name record to jump to an object record, it might be relevant to know to which data source exactly you are jumping (the context in which the target record will be opened), because you may have different access rights in different data sources. So a reverse relation text like Ob- jects {0} (creators) > this record, could become visible as Objects (Full object catalogue) (creators) > this record or Objects (Internal object catalogue) (creators) > this record for example, depending on the actual target data source name. 3. In the Relation format string property on the Relation fields tab, enter a format string containing fixed text and fields from the linked records that should be displayed in the Related records view per linked record for a forward relation. You can enter fixed text and spaces and field tags enclosed in %. Choose fields that re- ally identify the linked record to the user. You could just enter %BA % to show the name field, or %BA%, %do% for example, to show name and name type separated by a comma and a space.
29
4. If the current database (Collect in this example) is also specified as a feedback database in the linked database (People in this ex- ample), then the Format string for this feedback database will (also) be used in the Related records view in Axiell Collections (from version 1.0.6456.8217) for the reverse relation of sin- gle-sided linked fields in databases linking to the current data- base: if a feedback database format string is missing, the format string for reverse relations of such linked fields will automatically be constructed by Axiell Collections using the fields from a rele- vant brief display screen. See the screenshot below for an exam- ple of a format string. The fields in the Format string are fields from the feedback database (Collect in this example). If you find that the Format string for some feedback database already has content, then you can probably leave it as it is.
30 Step 2b: configure your selection of reversely linked fields For two reversely linked fields such as loan.in.number in Collect and object-in.object_number in Loans you configure relations as fol- lows:
1. In the Relation texts box on the User interface texts properties tab of the first linked field, loan.in.number in Collect in this example, you specify the forward relation label in as many interface lan- guages as are available in your Axiell Collections application. You can use a text like This record > incoming loans to indicate that underneath this label the user will find a list of links from the current object record to incoming loans records. Do not enter any texts in the Reverse relations texts box. Reverse relations would be redundant. 2. In the Relation format string property on the Relation fields tab, enter a format string containing the fixed text and fields from the linked records that should be displayed in the Related records view per linked record for a forward relation. You can enter fixed text and spaces and field tags enclosed in %. Choose fields that re- ally identify the linked record to the user. For example:
31
3. In the Relation texts box on the User interface texts properties tab of the second linked field, object-in.object_number in Loans in this example, you specify the forward relation label in as many in- terface languages as are available in your Axiell Collections appli- cation.
You can use a text like This record > objects to indicate that underneath this label the user will find a list of links from the cur- rent loans record to object records. Do not enter any texts in the Reverse relations texts box. Reverse relations would be redundant. 4. In the Relation format string property on the Relation fields tab, enter a format string containing the fixed text and fields from the linked records that should be displayed in the Related records view per linked record for a forward relation. You can enter fixed text and spaces and field tags enclosed in %. Choose fields that re- ally identify the linked record to the user. For example:
32 4.3 Adding a simple search option In the context toolbar above the result set view in Axiell Collections, you have the option to quickly execute a new search by selecting a field from the drop-down list of all indexed fields in this database, af- ter which you simply enter your partial (truncation required) or whole search key in the Enter search key box and click the magnifying glass.
Besides the full list of indexed fields, you can add a simple search op- tion which can search multiple indexed fields at once. In the screen- shot above it's called
33
5. At the bottom of this properties tab, in the Simple search fields box enter one or more field tags (one tag per line) for which an index exists. (These indexes may in turn index just a single field or multiple fields.) The field tags do not need to be of the same data type. There's no comfortable way here to look up the tags you need, so you'll have to do that in the database definition.
6. Save your changes in the application definition. 7. You may have to recycle your Axiell Collections IIS application pool before the changes become visible in Axiell Collections.
34 4.4 Adding a bulk insert option If you'd like users to have the possibility to create multiple new records with some identical data at once, you can set up a Bulk insert method for this purpose.
However, a bulk insert icon will appear in the result set context tool- bar by default (if the user has write access rights), regardless of whether you have set up the relevant method for the current data source, but its functionality will differ: if it hasn't been set up at all for the current data source, the window which opens will be titled New record and the user will only be allowed to create a single new record. If, on the other hand, the functionality has been set up all right for the current data source, the window will be named Bulk create and the user will find a Count box at the top of the window. In Count, the user must specify the number of identical records to create, while the data entered in the available fields will be stored in all those new records.
Data entered in uniquely indexed fields, like Object number in model applications, will automatically be made unique with a sequential number. For example, if the user bulk creates three records with ob- ject number ABCD-001, then the automatically generated object num- bers will be ABCD-0011, ABCD-0012 and ABCD-0013. Which screens are present in the Bulk create/New record window de-
35
pends on the setup of this functionality: by default all detail screens will be available to the user, but with a specific setup you may limit the number of screens displayed in that window. After the records have been created, the user can of course edit them one by one to add data unique to each record. Set up this functionality as follows: 1. In the data source in the Adlib application definition in which you’d like to offer the functionality, add a new method of Method type Bulk insert and add Menu texts in the required languages.
2. Create one or more normal detail screens or search for existing, appropriate screens containing all fields users might like to fill in when bulk creating records and associate them with this method: right-click the method in the tree view on the left, choose New > Detail screen and select the desired screen file via the … button on the Detail screen properties tab to associate a screen with the method. 3. Save your changes in the .pbk and recycle the Axiell Collections application pool.
36 4.5 Adding the Change locations procedure The Change locations procedure is optional extra functionality for Ax- iell Collections. This procedure allows the user to change the current location of objects registered in one or more marked records in the re- sult set all at once and update the location history of those object records at the same time. This is handy if a part of, or all of the col- lection changes location and you have actually moved the objects. The Change locations procedure can be set up via Adlib Designer in combination with custom adapls and screens. We already made the required adapl and screen (available for download here). You only still need to set up the procedure properties in your application if the Change locations procedure is not available in your Collections appli- cation yet. However, let's start at the beginning to show you how everything comes together. Imagine an icon being available in the context toolbar above the result set in Collections, with which you can select and run a custom task: currently that'll be the Change locations procedure so we'll limit our explanation to how this procedure works. (The icon be- comes active as soon as you've marked one or more records.)
A screen will open allowing the user to enter data relevant to this pro- cedure, after which clicking OK will run an adapl program that will be executed for every marked record in the result set, processing the en- tered data into each record. So the adapl must fill in the new current
37
location and update the location history. To get entered data from the task screen to the adapl we must define so-called parameters per task as if they were fields and use these parameters as task screen field tags on the screen and as source field tags in a special PARAMETERS FACS declaration in the adapl. Although these parameters look a lot like normal fields, they must be set up in the application definition, per task, instead of in the database definition and therefore they have no relation nor interference with the normal database fields. To an Axiell Collections web application based on an Adlib model appli- cation version 4.2 up to and including 4.5.1, the following applies: 1. For the Change locations procedure we rebuilt the Adlib for Windows dialog as a screen and assigned some parameters as field tags. We chose P1 for the new checkbox and existing Collect field tags for the other fields (because we've copied those fields anyway), but we could have chosen any twelve two-character pa- rameters for this particular purpose: no need to check the data- base definition of Collect per se. We called the screen changeloca- tiontask.fmt but any other descriptive name would have been fine too.
Note that during operation the Location field is hidden as soon as the user marks the To normal location checkbox, because of the field suppress condition P1 != '0' (here in Collections, logical field expression values are treated as an integer). 2. We created a ChangeLocation.ada/bin adapl to process the data from these parameters into each selected record. The .ada is
38 readable in a text editor like Notepad++ and documented well, so you can open it if you'd like to see how it is programmed or if you'd like to make changes to it. Without going into too much de- tail here about the adapl, it suffices to say that the adapl is struc- tured like an output adapl: it is run for each record separately and therefore has direct read access to all field tags from the pro- cessed record. To be able to write altered data to these tags, we could have used a FACS declaration but instead we chose to write to the _LOCAL FACS buffer, which has the same result but is a more concise way of programming this adapl. The only FACS defi- nition really required is the one for PARAMETERS (always use this name):
fdstart PARAMETERS '' P1 is PARAMETERS_tonormal 2A is PARAMETERS_location 2a is PARAMETERS_locationlref 2C is PARAMETERS_date 2G is PARAMETERS_time 2R is PARAMETERS_executor 2E is PARAMETERS_suitability 2F is PARAMETERS_authoriser 2f is PARAMETERS_authoriserlref 2D is PARAMETERS_locnotes mT is PARAMETERS_method mt is PARAMETERS_methodlref mR is PARAMETERS_reference mC is PARAMETERS_contact mc is PARAMETERS_contactlref mN is PARAMETERS_movnotes fdend
As you can see, the FACS declaration treats the twelve parame- ters as if they were regular field tags and assigns aliases to them so it's easier to work with them. There's no need to OPEN this FACS declaration since it is not a real database: after this declara- tion we can just use the FACS parameter aliases as if they were normal FACS field tag aliases. 3. In the Designer Application browser, open your application defini- tion and the data source under which the task must become avail- able, the Internal object catalogue for example (and/or the Exter- nal object catalogue and the Archives data sources, when it comes to the Change locations procedure). Right-click the data source and select New > Task in the pop-up menu.
39
4. Select the new task and on the Task properties tab, set the path to the screen and the adapl created for this task. Also set a de- scriptive menu text in as many translations as your application needs to be available in. This text will be visible as the tooltip text when the user hovers the mouse cursor over the Change locations icon. (If you specify multiple tasks in this data source, make sure that at least the English menu text is unique, so there shouldn't be another task in this data source with the same English name.)
40 5. Finally, define all used task parameters underneath the Fields header of the new task in the tree view.
41
For each parameter that has no correlating field definition in a database definition somewhere, right-click the Fields header un- derneath your new task and select New > Field in the pop-up menu to create a new field definition, like you would for P1. Task field definitions which can be copies of existing database field defi- nitions, can simply be copied from those database definitions and pasted underneath the task Fields list, also using the right-click pop-up menu: linked fields still need a linked database and a link reference field, but Relation fields tab properties and Linked field mapping tab settings do not apply to a task parameter. Fill out or check the appropriate parameter properties as you would for database fields. P1 for example, is a checkbox, so its Data type must be Logical (Boolean). If tag 2R (executor) is a plain field (which is the default case), you could consider setting the Type option on the Default values prop- erties tab to User name if you’d like the Executor entry field to contain the (overwritable) user login name as soon as the Change locations window is opened, if the executor of the physical move is likely to be the same person who registers the move. If the execu- tor is always one and the same person, you could set the Type property to Value instead and enter his or her name in the Text list underneath it. 6. To copy your new task to another data source, simply right-click the relevant task and select Copy in the pop-up menu. Then right- click the other data source and select Paste in the pop-up menu. 7. Save your changes to the .pbk after you've specified all parame- ters for this task. Then recycle the application pool for Axiell Col- lections so that the application definition can be reloaded. The functionality still has some shortcomings: The user won't get any warnings about errors or skipped records, neither will any log be created, so a manual check of the pro- cessed records afterwards may be required. In the adapl it is not enough to fill the link reference tags of the target record: the linked field itself must be filled with the re- solved value too. Note that even though tasks are not supported in Adlib for Windows, setting up a task in a .pbk breaks backward compatibility with Adlib 7.4 or older.
42 4.6 Adding a location context column to the link screen The link screen for linked location fields (used for the View table tab in the Find data for the field window when looking up or validating an entered value in a location field in an object or location record or in the Change locations procedure, usually doesn’t contain a context field column showing the upwards hierarchy of the selected location. This becomes an omission when you have a lot of non-unique location names: you would need to see the upwards hierarchy of each listed location to be able to select the proper one. The field columns you see on the View table tab are determined by the so-called link screen set up for the relevant linked field (see the Link screen option on the Link screens tab in the properties of a linked field in the database definition). (For the current_location.name field in model 4.5.2 for example, this is the lnk_location.fmt screen file.) Proceed as follows to add a context field column to a link screen: 1. Since a link screen contains fields from the linked database, we need to create a new field in the linked database, in Location in this case (4.5.2 already has some context fields, C1 being the rel- evant one for the current location) of the data type Temporary or Text, which is sufficiently long to contain all the terms of your most extensive term hierarchy. Use a unique field tag and choose a meaningful field name: part_of.context for example. If you make it a Text field, then also mark the Do not show in lists option for the field. 2. For the internally linked field in Location containing the broader lo- cation (tag 2A in Location in 4.5.2), now set the Context field property on the Relation fields tab to the actual context field (C1 for example). Save the changes in this database. 3. Place the context field on the link screen (lnk_location.fmt in this case). You can leave its properties to their default. Place the field somewhere in the row of fields already present, place the label above it and name it appropriately: Context or Location hierarchy, for example. If the link screen already contained an Is part of field (for the broader location only) you may consider removing that from the screen since the Context field will contain this informa- tion too. Save your changes. Recycle the Axiell Collections application pool and log in to Collections again. If you now open the Find data for the field window for any of the linked location fields in object records and switch to the View table
43
tab, you should see the extra context column showing the upwards hi- erarchy for the selected location. For the Change locations procedure, the same link screen is used when you look up available location names for the Location entry field.
44 4.7 How to include original linked file names When you link an image file to a record, the selected image file will be copied from the original location to the local \images subfolder of your Axiell Collections folder for this purpose and will then be assigned a new file name to prevent it from accidentally overwriting any earlier linked files with the same name. This new, unique file name will then automatically be registered in the media record. However, this file name is not based on the original file name and sometimes you would like to register this original file name in the me- dia record too, because the name contains an indication of what the image portrays or because you’d like to be able to search on the file name. Axiell Collections can automatically register the original file name in the media record too, but you’ll have to configure your Col- lections application accordingly first. Proceed as follows: 1. In both the Collect and Media database structures, define a flat, text field of sufficient length to contain each conceivable file name. In Collect, the new field should be repeatable and be part of the same field group as the linked image reference field (which usually has tag FN). 2. In Collect, on the Linked field mapping properties tab of the linked image reference field (usually tag FN) add a field mapping from the new field in Media to the new field in Collect in the Copy fields from linked record mapping and create the reverse mapping in the Write fields to linked record mapping. This way, Collections can write the original file name to a newly created media record or re- trieve it if you choose to display the field on the Reproductions screen of object records. 3. Since Collections doesn’t know which tags you have used for your new original file name fields, you must add an appropriate config- uration to your Axiell Collections settings.xml file, within the
45
The
46 4.8 Setting up connect entities In essence, a connect entity is a user-friendly way to take a field val- ue from marked records in one data source and copy that to another field in marked records from a second search result (or to a new record) in another data source. The most likely implementation of this principle will be bulk linking, where the user links all marked records in the current data source to a record in another data source, to link a set of objects to an outgoing loan or an exhibition for example. Once set up properly, a Links drop-down list in the context toolbar of the Result set will offer one or more options. Prior to selecting one of the options, the user must mark the desired records for the operation. Then a Links option must be selected and activated by clicking the chain icon next to the drop-down list. A Search window will open, allowing the user to search for a second batch of records or to create a new record in the other data source to link the initial selec- tion of records to.
The setup is constructed in such a way that it doesn't matter which of the source and destination fields is a linked field, it is even possible to set plain fields for both the source and destination field. Depending on the nature of the source and destination field, a connect entity can behave in two different ways: If the source field is a plain field while the destination field is a linked field or plain, then the value from the source field will be copied to the destination field (and will be resolved if it concerns a linked field) If the source field is a linked field while the destination field is a plain field, then the value from the destination field will be copied to the source field and will be resolved.
47
Proceed as follows to set up one or more connect entities in a data source: 1. Right-click the data source (or the Connections list header under- neath it, if present) and choose New > Connect entity in the pop- up menu. 2. Select the other data source for this connection in the Connected data source drop-down list. 3. In the Source field property, click the ... button to select a field in the current database: you can pick a plain field or a linked field. In the screenshot above, object_number is a plain field. 4. In the Destination field property, click the ... button to select a field in the other database: if you picked a linked field as the Source field, then pick a plain field as the Destination field; if you picked a plain field as the Source field, then it doesn't matter if you pick a plain or linked field as the Destination field (as long as it serves your purpose). In the screenshot above, the ob- ject-out.object_number field is a linked field. 5. Add appropriate label translations in the Text box. These labels will appear in the Links drop-down list in the Result set context toolbar of the data source in which you created this connect en- tity. 6. Save your changes and recycle the Axiell Collections application pool.
48 4.9 Implementing pseudonyms Pseudonyms are a new internal link type in model application 4.5.2, but it can be implemented in older applications too. In a relation of this type you can associate proper names (aka "main" names) with pseudonyms. This allows you to register e.g. the proper name of an author as well as his or her pseudonym(s) in the Persons and institu- tions data source and link these names to each other in a way that doesn't prefer one name over the other. This type of relationship is somewhere in between a preferred term relation and an equivalent re- lation, because between names in a pseudonym relationship a hierar- chy does exist but no non-preferred term substitution will ever take place. An equivalent relation has no hierarchy. The Standard and Advanced search in Axiell Collections allow the use of a new pseudonym operator when you search Persons and institu- tions or when you search a field in another database, linking to Per- sons and institutions. When you are searching using pseudonym, you search on the proper name and all its pseudonyms as specified in the Pseudonym entry field (in Persons and institutions), provided these names have the same domain (name type) as the linked field you are searching. It doesn't matter if the name you enter is a proper name or pseudonym and it also doesn't matter if the search key actually does appear in records for the search to succeed on the other names in the pseudonym relation. For example: author.name pseudonym "Kopland, Rutger" In this example all records would be retrieved in which the author name is either the search key itself or the proper name or any pseu- donym of the search key. Pseudonyms can be entered in Persons and institutions records once relevant fields and internal links have been added to the database structure and screens. When your application is ready for it and you've actually registered pseudonyms and you try to validate field data linking to Persons and institutions, you may encounter the fol- lowing icons in the first column of the list on the View table tab of the Find data for the field window:
A grey star indicates a proper name while an open star indicates a pseudonym. Pseudonyms can be registered in linked fields just like proper names: there won't be any automatic substitution of names.
49
As mentioned, you need to set up pseudonym fields first, before you can register pseudonyms. Proceed as follows: 1. In the people.inf database structure, create two linked fields pseudonym and pseudonym_for with accompanying link reference fields. The relevant properties of the two linked fields are: Maxim- um length 255 (as long as the Name field); Repeatable marked for pseudonym, deselected for pseudonym_for); Linked database folder . and Database =, Lookup field name and use accompanying link reference field, No domain, Strict validation, Link only first oc- currence and Allow the creation of new linked records should be marked; Relation fields Preferred field use, Equivalent field equi- valent_name, Broader field part_of, Narrower field parts, Re- lated field relationship, Pseudonym For field pseudonym_for, Pseudonym field pseudonym; Link screen ../screens/lnkaddr, Zoom screen ../screens/zm_organ, Zoom/edit screen ../screens/zm_organ; Linked field mapping Source field name and Destination field pseudonym (if that is the current field) or pseudonym_for if that is the current field. 2. Create integer indexes for both link reference fields and reindex them (to create the relevant SQL tables). 3. Add an internal link to the people.inf, with the following proper- ties:
4. Now you need to set the relation fields for pseudonym and pseud- onym_for for all fields in other databases linking to the people database. Luckily you won't have to do that manually, but still there's some work involved: just start at the top of the database list in the tree view in the Application browser and click the Fields list header of a database structure to open the fields list in the right window pane; in there, click the Linked database column header once or twice to sort the list so that all fields linking to people are grouped; select all these linked fields by clicking the first field and then Shift-clicking the last field; right-click this 50 field selection and choose Set relation fields in the pop-up menu to set all available relation fields automatically. Do this for every database except for people.inf.
5. Edit the name.fmt screen and add the pseudonym fields, Pseud- onym is a repeated field, Pseudonym for is not repeatable.
6. Save all your changes and recycle the Axiell Collections application pool.
51
4.10 Creating output formats for Collections In Axiell Collections you can export or print data from either the cur- rently displayed record, the currently marked records in the result set or all records in the result set, via the Create a report with a pre- defined output format icon and the Output formats dialog it opens:
Each data source can offer its own output formats. Some default out- put formats may or may not be present in a data source: the four Word templates visible in the screenshot below, for your objects data sources (like the Internal object catalogue), can be downloaded here if they aren’t present in your application already.
Axiell Collections supports Word templates with the .docx extension, it supports output adapls using the wordcreatedocument function (to print from a .docx template), it supports output formats which have
52 been specified as a combination of an adapl and a .docx template, and it also supports XSLT stylesheets as output formats. It does not sup- port output adapls using print and output statements to print stuff, nor does it support Word template output formats with the .dot and .dotx extension. Please see the Programming XSLT stylesheets for Adlib and Axiell guide, chapters 1.2.6 and 2.2.2 for more information about creating XSLT stylesheets for Collections: XSLT programming experience re- quired. Word templates however, are much more accessible and easier to cre- ate than XSLT stylesheets, as we’ll show in the next paragraphs. Users do need to have Microsoft Word 2007 or higher installed on their computers to be able to export data to a Word document (and possibly print that document), using Word templates. Users may even create their own templates, although an application manager may be required to link new templates to data sources. There is currently no functionality to print to a custom template which hasn’t been set up as an output format yet, like there is in Adlib.
For experienced Adlib users: template format differences
53
Word template output formats for Collections are very similar to those for Adlib for Windows. Unfortunately you cannot reuse your old .dot or .dotx templates just like that: you’ll first have to convert them somewhat. That shouldn’t be hard in most cases though. The most rel- evant differences between the two template types are that for Axiell Collections: the file extension shouldn’t be .dot or .dotx, but .docx: this is sim- ply a matter of opening a new document based on your .dot(x) file and saving that file under the same (or another) name but with the .docx extension; Label templates aren’t supported by Axiell Collections (yet). to print a specific field occurrence (regardless of whether the field reference is located in fixed text or in a table) you must indicate the relevant occurrence number in square brackets behind the tag in the field reference, like so <
54 the <<[PageBreak]>> parameter nor a table with the <<[Start- RecordList]>> and <<[EndRecordList]>> parameters (which are also supported) print processed records directly below each other; you can use Word document “sections” for more complex docu- ments: for each processed record, relevant data is appended to each section (so sections are not repeated for each processed record) and any sections are filled simultaneously; after setting up a new .docx template as an output format, you must recycle the application pool under which Axiell Collections runs, so that Collections may reload the application structure; when testing printing to your template from within Collections after making changes to the template (that you set up as an output for- mat earlier), you don’t need to recycle the application pool again: Collections automatically reloads the template. Just remember to close the template before you print to it; when printing from a browser you may notice the browser warns you for a pop-up being blocked: you’ll have to accept the pop-up but if you don’t like these messages you can either try to include the Axiell Collections website in your browser list of trusted appli- cations or switch off pop-up blocking via your browser’s settings; Below you can see some examples of templates: just copy one of the tables to a .docx document, set it up as an output format for your In- ternal object catalogue and you can start experimenting with it. Example 1: images will only have a fixed maximum width, while the height is variable, and only the first occurrence of each field will be printed. Check the properties of the FN table cell by opening this docu- ment in Word, by right-clicking the table cell and selecting Table prop- erties in the pop-up menu.
Image Object no. Object name Creator <<[StartRecordList]>> <
Example 2: images (of which only the first occurrence will be printed) will have a fixed maximum width and height and all occurrences of the other fields will be printed below each other but still within their origi-
55
nal cell. Check the properties of the FN table cell by right-clicking it and selecting Table properties in the pop-up menu.
Image Object no. Object name Creator <<[StartRecordList]>> <
<<[EndRecordList]>>
Example 3: images will have a fixed maximum width and height and only the first occurrence of each field will be printed. Check the proper- ties of the FN table cell by right-clicking it and selecting Table proper- ties in the pop-up menu. Each record will be printed on its own page.
<
______<
<<[PageBreak]>>
56 Creating a .docx Word template for Collections Creating a Word template for Axiell Collections (that works in Adlib for Windows too) is fairly easy, especially if you’ve created documents in Microsoft Word before. Essentially, the procedure is as follows: 1. Start Microsoft Word (2007 or higher) and open a new, empty document. It depends on your version of Microsoft Word, how to proceed. The following description pertains to Office 365 Word. See your Microsoft Word manual if you have a different version, or if you seek more information about the functionality of that soft- ware. You can already save it in the Worddoc\templates subfolder of your Adlib main folder (the location where you typically store all Word templates) under a practical name, in the .docx format (not .doc, .dot or .dotx). For an English template, let the name of your template end with the interface language number 0 (see the following paragraph for information about naming templates ac- cording to their fixed text language.) Save you additions and changes to this template regularly.
2. In the new document you can add and lay out text just like in a normal document. Every time you use this template (from Collec- tions or Adlib), this text will automatically appear in the generated document. 3. If you wish to output data and/or images from your database re- cords to this template, you must place a reference in the template for every field you wish to include. In the following paragraphs you’ll find example templates for letters and record lists, but the basic procedure is as follows: at the desired location in the tem- plate, type the field name (use only the English field names) or tag of the field between double angle brackets, and type these ex- actly as they have been defined in the data dictionary of the cur- rent database. (You can only include fields from the current data- base, plus merged-in target fields that come with linked fields, in a template.) Field names and tags are case-sensitive, so use <
57
It is possible to print only a specific occurrence or to print all oc- currences of a field: see further paragraphs for more information. For a multilingual field, you can choose to specify the language in which the data should always be printed or to leave out a lan- guage specification to have the data printed in the data language (not the interface language) currently active in Collections.
After switching the interface language of Collections to English, you can find the English data dictionary field name and field tag of a field by hovering the mouse cursor over it in edit or display mode. In the example below, object_number is the data diction- ary field name and IN the field tag. You can choose which to use.
Naming conventions for templates Microsoft Word templates which are available as output formats in Collections, are interface language and data language dependent. This pertains to templates which have been linked to the application via Adlib Designer, and which can be seen in the Output formats dialog. (Information about setting up output formats for your application can be found at the end of this chapter.) Data language dependency means that if a field is multilingual, then only the value in the currently active data language will be printed (unless the field reference in the template contains a specific language code to instruct Collections to always print that particular language value). For the user, interface language dependency means that a selected template will usually contain fixed texts (like field labels) in the cur- rent interface language of Collections. For example, if you display the menu’s and screens in Dutch, then you’ll automatically be working with Dutch templates (if available). For the maker of templates, inter- face language dependency means that you have to create a separate template for each interface language in which users may want to work. So, of the same template there may exist different translations, each in its own file, for every interface language that you wish to make available to users of your application. For example, if your application is being used by Dutch and English speaking users, then you should 58 have at least a Dutch template and an English template for each print task. Axiell Collections recognizes the language of a template by the num- ber at the end of the file name: 0 = English, 1 = Dutch, 2 = French, 3 = German, 4 = Arabic, 5 = Italian, 6 = Greek, 7 = Portuguese, 8 = Russian, 9 = Swedish, 10 = Hebrew, 11 = Danish, 12 = Norwegian, 13 = Finnish and 14 = Chinese. So a new template for printing an accessions list, with English texts on it, should be named something link accessionslist0.docx. The same template, translated to Dutch, then becomes accessionslist1.docx. (Note that you must keep the name of the file untranslated.)
Creating standard letters without tables Field references can be placed in between other text, or anywhere else on a page. This lets you create, for instance, a standard letter template for the Persons and institutions data source, as in the follow- ing example: To: <
Axiell ALM Netherlands BV Safariweg 18-22 3605 MA Maarssen Re: new service pack
Dear Sir/Madam <
Word will repeat this text for every record you export to this template, and will replace the field references with data from the processed re- cord. Normally, texts are pasted directly underneath each other; if you want every record (every letter) to start on a new page in the resulting document, you should enter a special parameter at the end of the document. (Parameters are not printed, but serve as instruc- tions to Word.) In this case, you should place the parameter
59
<<[PageBreak]>> at the bottom of the template. This parameter will make sure that every subsequent record will be placed on a new page. Further note that some field names have [1] behind them while oth- ers haven’t. With [x] (where x must be replaced by a number) behind the field name or tag in a field reference, you specify the occurrence of the repeated field to be printed. In .docx Word templates, all occur- rences of a repeatable field are printed by default, if you do not spe- cify an occurrence number. This applies to field references in both let- ters and records lists. So if you want to make sure that only the first occurrence of repeatable fields is printed, then specify [1] behind the field name. (If you’d rather have the second occurrence of a field, you’d specify [2].) Since the name field in the example above isn’t a repeatable field, we don’t need to specify the occurrence to print, al- though it wouldn’t hurt if we did either. If the occurrence you specify does not exist in the data, then the field will not be printed. This is a good way for making standard letter templates, which you can use to generate personalised letters automatically, for instance by using contact data from your database records.
Printing data from a repeated field group in a list In standard letters you may include tables to print data from a re- peated field group in a list: fields from the Dimensions field group on the Physicial characteristics screen tab of an object record, for ex- ample. In such case we typically like to print all occurrences of the re- peated field group. If we’d like to include the Part, Dimension, Value and Unit field in this list, then the template table could look as follows: Part Dimension Value Unit <
- > <
During printing, a new table row will be created for each field group occurrence.
Printing data from several records in a list To generate a list containing data from several records (marked in the result set) underneath each other in a table (instead of a letter format), place the Adlib field references inside a table in the template, next to each other in separate cells. You should also enter two para- meters in the rows just above and just beneath the references, to in- dicate that you wish to see a list of exported records in a table. In a top row you can also specify column headers, as follows:
60 First column header Second column header etc <<[StartRecordList]>> <
In a single template, a list of this type cannot be combined with a standard letter as described in the previous paragraph. For example:
Title Author Shelf mark <<[StartRecordList]>> <
In this case, the table prints all occurrences of the fields (underneath each other in separate paragraphs, but within a single cell. So two re- cords, of which the first has two titles and three authors, would be printed like this: Title Author Shelf mark The house in Mokum Dalum, P. van HU.3928.12 House in flames Akers, H. Scot, V. Four seasons in a day Bufels, F. ZK.3877.33
If you’d like only the first occurrences of a field, like the title, to be printed, then simply add the desired occurrence number behind the field tag in the reference:
Title Author Shelf mark <<[StartRecordList]>> <
You can enter only one field reference per cell. The cell may further contain extra text next to the field reference, although that fixed text would be repeated for every printed field occurrence. Another limita-
61
tion of record lists is that you can only use one row of field references, and you cannot place a line of fixed text underneath them, only a row with the parameter <<[EndRecordList]>>. The <<[StartRecordList]>> parameter should be placed immediately above the row of field references. Only the first row of the four is op- tional, in which you can enter fixed texts to serve as column headers. The rows in which records will be printed, can be numbered sequen- tially if you want. You can achieve this by inserting an automatic num- ber in an empty cell of the table row in which the field references are located. Use the Word Numbering function for numbered lists for this. The automatic number will be incremented automatically with each re- cord inserted in a following table row. When a record list is long, the table will automatically continue on the next page. If you want the table header row to be repeated at the start of every new page, you should set this in Word: 1. Select the top row of cells in the table by clicking the margin just in front of it. 2. Right-click the selection, and from the pop-up menu, select the option Table properties. 3. In the Table properties window, select the Row tab. 4. Check the Repeat as header row at the top of each page option. 5. Click OK. The table borders can be made invisible (or thicker) by adjusting Bor- ders and shading, through the Table properties (see your Word manu- al for a list of options). You can also change the cell alignment and margins to obtain a decent layout.
It is not possible to print a standard letter for every record from the currently opened database and follow each record by a record list from another database. For this you’ll have to create two separate templates, one for the letter and one for the record list, and print re- cords separately from the relevant databases to the different tem- plates.
Printing images Images in records can also be printed to a Word document. In the template, include a field reference with the tag of the relevant field*, just as you would for other fields, to include the image. A reference to an image field could be: <
62 A reference to an image field can be included in a Word template in several ways, with different results, although the aspect ratio of each image will always remain intact. Of the methods described below choose the one that best fits your requirements. The original size of the image often plays a role in the outcome as well: the physical dimensions of an image (in inches or centimeters) is determined by the combination of the resolution of the image and the DPI/PPI value stored in the image file.
* Technical information
In Adlib Designer, with the definition of fields in the database specific- ation (also called data dictionary), a data type has been set. This type determines what users can and cannot enter in such a field. The type of the field containing the hyperlink or path to the image must be IMAGE, and it must also have been defined as such in the data dictionary; this is usually the case. (If the field type is not IM- AGE, the URL or path itself will be printed, instead of the image.) Database fields of the APPLICATION type (e.g. Identifier in library ap- plications) can refer to images, amongst others, but these images cannot be printed to Word.
Method 1: directly in a paragraph If the field reference appears randomly in a paragraph on a page, the image will be printed in its original size (as far as the page size al- lows).
Method 2: in a table cell Insert the field reference inside a table cell in the preferred spot on the page and specify at least a prefered column width of the column to indicate the maximum width of the image; the image will be scaled down if it is too large. The height of the row can be fixed as well by setting an exact row height in the row properties to limit the height of printed images or leave the row height unspecified to keep it flexible. To make sure a fixed number of records is printed on a page, you best limit the row height so that tall images won’t mess up your layout. Using the following template, would generate a document like the one below:
63
<
64 Printing barcodes During printing you can have IDs like object numbers automatically converted to a barcode. You can print barcodes using XSLT stylesheets or Word templates. To be able to print a barcode to a Word template, a barcode font needs to be installed on the computer from which the user will do the printing. (The possibility to include a font in a template, is not functional yet.) So you first need to obtain a barcode font, either free or paid, with a sufficient license. See your
65
Windows Help for information about how to install a font under Windows. Note the difference between so-called code 39 and code 128 barcode fonts: code 39 can only convert letters, numbers and the fol- lowing symbols: * $ % + - . and /. Code 128 on the other hand, is able to convert all 128 characters of ASCII, but this font type is cur- rently not working for Collections. TrueType code 39 barcode fonts are currently functional. In the Word template itself, first enter the field reference like you would normally: a barcode can be printed in its own paragraph or in- line. An object number field reference for example: <
If the field reference is placed inline, then select the whole field refer- ence and apply the barcode font. For example:
To print a human-readable version of the object number as well, sim- ply insert <
Printing multilingual data via Word templates You can use the field reference in a Word template to specify which language value of a multilingual field must be printed. You can provide a specific data language via an IETF language code like nl-NL for Dutch or en-GB for British English for instance, or no data language at all to print data in the currently set data language in Collections.
66 In a field reference in a Word template it simply comes down to being able to specify not only an occurrence number but a language code as well, <
Examples Below you’ll find some examples to clarify things. Suppose you’re us- ing a multilingual database in which you can enter both Dutch, English and French data in the Object name and Title fields. As usual, you can select a data language via the Data language button in the Edit menu.
Then assume you have a record containing two object names and a ti- tle in all three languages, for example:
Example data
(nl-NL) Object name (occurrence 1): tekening Object name (occurrence 2): topografische tekening Title: Tekening in pen en penseel, voorstellende de Grolsteeg te Harderwijk, door Joh. van Bijsterveld, 1965 (en-GB) Object name (occurrence 1): drawing Object name (occurrence 2): topographic drawing Title: Drawing in pen and pencil, representing the Grolsteeg in Hard- erwijk, by Joh. Van Bijsterveld, 1965 (fr-FR) Object name (occurrence 1): dessin Object name (occurrence 2): dessin topographique Title: Dessin a la plume et au pinceau, représentant la rue Grolsteeg à Harderwijk, par Joh. van Bijsterveld, 1965
Below you can see an example template which experiments with the different possibilities of explicit or implicit printing of a language val- ue. (The four table cells automatically print all occurrences.)
67
Example template
Tag OB: <
<
Tag TI: <
<
The result if the currently set data language happens to be Dutch:
Printing result
Tag OB: tekening Tag OB[2]: topografische tekening Tag OB[fr-FR]: dessin Tag OB[2,en-GB]: topographic drawing Field object_name[1,fr-FR]: dessin tekening topografische tekening
drawing topographic drawing
68 Tag TI: Tekening in pen en penseel, voorstellende de Grolsteeg te Harder-wijk, door Joh. van Bijsterveld, 1965 Field title[1]: Tekening in pen en penseel, voorstellende de Grolsteeg te Harder-wijk, door Joh. van Bijsterveld, 1965 Tag TI [fr-FR]: Dessin a la plume et au pinceau, représentant la rue Grolsteeg à Harderwijk, par Joh. van Bijsterveld, 1965 Tag TI [1,en-GB]: Drawing in pen and pencil, representing the Grolsteeg in Harderwijk, by Joh. Van Bijsterveld, 1965 (en-GB) Field title[1,nl-NL]: Tekening in pen en penseel, voorstellende de Grolsteeg te Harder-wijk, door Joh. van Bijsterveld, 1965
Tekening in pen en penseel, voorstellende de Grolsteeg te Harder-wijk, door Joh. van Bijsterveld, 1965
Drawing in pen and pencil, representing the Grol- steeg in Harderwijk, by Joh. Van Bijsterveld, 1965 (en-GB)
Invariancy of one of the translations of field data also plays a role. To be precise: If in the template field reference (to a multilingual field) a data language is specified: if a value in that language is present then that is printed, if not, then if a value in the invariant language is present, that will be printed instead, otherwise no value is printed. If in the template field reference (to a multilingual field) no data language is specified: if a value in the current data language is present then that is printed, if not, then if a value in the invariant language is present, that will be printed instead, otherwise no value is printed.
Summary of supported parameters You can send specific commands to Word by placing extra parameters in the Word templates. The following commands are currently avail- able: <<[PageBreak]>> Every new record is printed on a new page. Do not use this command in labels or in a template containing a re- cord list.
69
<<[StartRecordList]>> and <<[EndRecordList]>> Use these parameters to create a record list with a table. (Cannot be used together with <<[PageBreak]>>.)
Setting up an output format in Designer Once you’ve created your own Word template, it must still be linked to the data source it was designed for. Proceed as follows: 1. Underneath the desired data source in your application definition in the Adlib Designer Application browser, right-click the Output jobs list header and select New > Output job in the pop-up menu.
2. In the properties of the new output format, enter the job title in as many translation as you’d like the functionality in your applica- tion to be available to users. Make sure the title describes the out- put format clearly.
70 3. Behind the Template path property, click the … button to locate your new template.
To find your .docx template in the proper folder, set the drop- down list in the right bottom corner to All files (*.*) first, other- wise the .docx files won’t be listed. Select one of the translations of the template you made: it doesn’t matter which.
4. In the entered Template path, now remove the language number from the file name. This way Collections can automatically pick the right language version of the template, depending on the current interface language in Collections:
71
5. Repeat this procedure for any other data sources you’d like to add the output format to and then save your changes to the applica- tion definition. 6. Recycle the Axiell Collections application pool in IIS so that Collec- tions may reload the application structure and you are ready to test* your new output format. 7. If you make changes to your template after testing it in Collec- tions, you don’t need to recycle the application pool again: Collec- tions automatically reloads the template each time you print to it. Just remember to close the template before you print to it. * When printing from a browser you may notice the browser warns you for a pop-up being blocked: you’ll have to accept the pop-up but if you don’t like these messages you can either try to include the Ax- iell Collections website in your browser list of trusted applications or switch off pop-up blocking via your browser’s settings.
72 Appendix A
On a host server, the Web Deploy tool must be present to be able to install Axiell Collections. If the tool is not present yet, you may install it as follows: 1. On the server where you’d like to install Axiell Collections, open the Server Manager.
2. Click the Local Server option in the left column. In the Properties box, check the IE Enhanced Security Configuration setting. If it is set to On, click the underlined On the open the Internet Explorer enhanced security configuration and set either Administrators (if you’re the administrator) or Users (if you are a different user) to Off. This will give you administrator installation rights on the serv- er.
73
3. Open IIS. In the tree view on the left, select the server level node. In the Action column on the right, click the Get new web platform components option.
4. Type “Web deploy” in the search box in the right upper corner of the Web platform installer and press Enter.
5. Add both the Web deployment tool 2.1 and Web deploy 3.6 and click Install to install them. 6. Close and restart IIS and the Deploy option should now be avail- able in the right-click pop-up menu for an application.
74 75