Adlib - Axiell
Axiell Collections
Installation and configuration
Axiell ALM Netherlands BV
Copyright © 2019 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 Netherlands BV. Axiell assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished 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 improved.
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 18
Login 19
3 Updating your Adlib application 21
Step 1: create a backup of your Adlib files 21
Step 2: run the ValidateDatabase tool 21
Step 3 (optional): clean up your data 21
Step 4 (for old applications): run ConvertInternalLinks 22
Step 5: convert your output formats 23
Step 6 (optional): set up Change locations procedure 26
Step 7 (optional): set up new Collections functionality 26
4 Application configuration options 27
4.1 Adding geographical maps functionality 27
4.2 Setting up the Related records view 31
4.3 Adding a simple search option 37
4.4 Configuring the bulk create records option 39
4.5 Adding the Change locations procedure 41
4.6 Add a location context column to link screen 47
4.7 How to include original linked file names 49
4.8 Setting up connect entities 51
4.9 Implementing pseudonyms 53
4.10 Image format strings for the Gallery view 56
4.11 Deep linking to records in Collections 57
4.12 Storing uploaded Word templates 59
4.13 Creating output formats for Collections 62
Creating a .docx Word template for Collections 67
Naming conventions for templates 69
Creating standard letters without tables 69
Printing data from a repeated field group in a list 71
Printing data from multiple records to a list 71
Printing images 73
Printing barcodes 75
Printing multilingual data via Word templates 76
Summary of supported parameters 79
Using a label printer 80
Setting up an output format in Designer 84
4.14 Setting up an IIIF image server 86
Appendix A 95
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 requirement is that the application data directory is actually accessible. 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 11.0 or higher. The server version of Calm must be installed; the client version can also be installed but is not necessary. We recommend 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.
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.
[pic]
In Windows 10 you would do this via the Windows Features dialog (Control Panel > Programs > Programs and Features > Turn Windows features on or off).
[pic]
Further make sure that (under Features) for the .NET Framework the WCF Services > HTTP Activation option is marked.
[pic]
In Windows 10 you would find it in the Windows Features dialog.
[pic]
• 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 . 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.)
[pic]
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 deployment, do make sure you have full access rights to the desired target 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 installed on the server, yet only when IIS has already been installed (with the latest security updates), otherwise some important features of will be missing from the installation. So on a new server, always install IIS before you install the .NET Framework. For information about the .NET Framework, see:
.
(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, 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.
• 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 assigned 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 network, within a workgroup, in which case each computer/server in the workgroup needs to have its own (matching) user accounts and security control to be able to share their resources. In this case, the Collections web application folder and the Adlib application folders require sharing and the anonymous IIS_USR user needs to have read-only access rights to these folders. Another requirement is that in IIS the Anonymous 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).
[pic]
2 Installing Axiell Collections
1. You have received the Axiell Collections deployment package
(Axiell.Alm.MVC.KendoSPA.zip) for Adlib or Axiell Collections.zip for Calm) 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.
[pic]
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 (Recycling) Regular time interval (minutes) to 0: this avoids unnecessary recycling of the application pool.
[pic]
[pic]
Also for performance improvement on startup, set the Start Mode to AlwaysRunning: this launches the worker process for the application pool as soon as IIS is started instead of launching it only when the first request for the web application is received. This option is available from IIS 8.
3. We recommend using HTTPS as the data transfer protocol. You would first need to acquire an SSL certificate from your local certification 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 requests to HTTPS, for example using URL Rewrite, a plugin for IIS. Information about how to set up a redirect can be found elsewhere: here for example.
4. In IIS, add a new application called Collections, underneath the Default Web Site, assign it your new application pool and mark the Enable preload checkbox (available from IIS 8) to speed up performance.
[pic]
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 visible. Right-click the Default Web Site (if you’d like the physical files to be installed in C:\inetpub\wwwroot\) or right-click the application underneath the Default Web Site (if you’d like the physical files to be installed in the folder containing the deployment package) and select Deploy > Import application. (You must also do this when you are about to upgrade an existing installation of Axiell Collections.)
6. In the Import Application Package wizard that has opened, Browse to your deployment package (Axiell.Alm.MVC.KendoSPA.zip or Axiell Collections.zip) and open it. Click Next.
7. In the following step, leave the selected Contents of the Package as is and click Next.
8. In the Application Path, either remove any text from the entry field to deploy the application underneath the remaining fixed 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 application there (in which case the physical files will be installed in C:\inetpub\wwwroot\). Click Next.
[pic]
9. In the Overwrite Existing Files step, choose the first option if you already have an Axiell Collections installation in place on that location, 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.
[pic]
10. Click Next to start the actual deployment now. After installation has finished, the wizard should report a successful installation. Click Finish.
[pic]
11. In IIS, right-click your Axiell Collections application and select Explore 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 application, amongst others.
13. This step in the installation procedure differs depending on whether 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).
Making sure that the Help is accessible
The Collections web server will always check if a topicmapping.xml file (required by browsers to open the Collections Help) is available at the specified location in the node ( by default) and will only offer the Help function in Collections if that check succeeds. Since this check will fail if your web server doesn’t have internet access, you’ll have to replace that URL by ~/App_Data/. So the node literally becomes ~/App_Data/
. Then the system will look for and load topicmapping.xml from the \App_Data folder which also contains the settings.xml file you are currently editing. The topicmapping.xml file in this folder will be updated automatically with every Collections update.
Using a singular Adlib application
In case of a default, singular Adlib installation where all users use the same application, you can leave as is. (The "SQL" id points to the SessionManager Id with the same name, so if you change the session manager id, you’ll have to match it in the SessionManagers Current setting.), for example:
The optional Scope attribute for the exists to differentiate front ends, since the Collections API can be used across multiple applications (Collections and Adlib Internet Server, for example). For a Collections application, set it to Collections. The option is relevant if indeed different front ends use this API and you don’t want actions like the resetting of all user-interface settings to their default (as can be done via the Settings button in the Collections main menu) to affect other front ends.
Languages is an optional setting to improve performance when a user logs in for the first time. By default (without the setting), Collections attempts to load all interface languages (languages used for field and button labels and such) available in Adlib Designer, even if there are no actual interface translations for those languages. This automatic detection of languages leads to a substantial pause the first time a user logs in. To speed things up, include this setting with a list of comma-separated ISO 639-1 language codes for the interface languages that are needed by your users and are actually available in Axiell Collections too. (Invalid codes will be silently ignored by Collections.)
CacheScripts (set to false) is an optional setting for development purposes, which enables the reloading of an adapl bin file each and every time it is called, so that recycling of the application 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.
ImageCachePath: with the ImageCachePath setting set to a full path*, Collections creates a \cache subfolder underneath your \images folder. Every time linked images are displayed resized in Collections a .bmp copy of the image in the displayed size(s) is stored in this folder so that next time the image must be displayed in the same size it can be retrieved directly without need for (time consuming) resizing. You can provide the setting with a different UNC path or local path as the Value if you’d like the image copies to be stored elsewhere.
* Note that the application pool user must have enough access rights to allow the implicit creation of a new subfolder and the writing of files in that folder. Check that the anonymous authentication credentials (which apply even before a user has logged in to Collections) have been set to Application pool identity.
[pic]
You’ll get there by first selecting your Collections application in IIS, then double-click the IIS Authentication icon, after which you right-click the Anonymous Authentication name and select Edit… in the pop-up menu.
[pic]
Preload: the Value indicates the level at which to pre-load parts 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 database/data source info), More (pre-loads basic schema info and commonly-used objects such as screens) 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 forces a preload of the application regardless of whether the tenant uses it and therefore increases baseline server memory and resource usage.
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 expected 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 enterprise multi-tenancy situation however (multiple instances of Collections 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 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++).
Making Help accessible offline
By default, Collections is set to use the Help documentation Axiell makes available online. If your users of Collections will always have internet access, there is no need to make any changes to Help.
If your web server does not have internet access, you can point Collections to the Help documentation that installs with the program, instead. To do this, find the section in settings.xml ( by default) and replace its contents with ~/App_Data/ (so the node literally becomes ~/App_Data/).
Using a singular Calm application
In case of a default, singular Calm installation where all users use the same application, change to . (This tells Collections to look at the "CALM" SessionManager section below. If you change the session manager id, you’ll have to match it to the SessionManagers Current setting). The CALM SessionManager section looks like:
The following Setting keys can be used to configure Collections:
Version: The version of Calm you’re running (e.g. version 11.0).
Server: The server Calm is located on.
Port: The port used to reach Calm. This is required if you are not running on default ports.
User and Password: To access Calm, Axiell Collections needs the credentials of a user set up in the Calm Admin program as an Administrator. This can be done in two ways:
• The best way to supply those credentials is by entering them into the Application Pool Identity section in step 2, above. This must be an active directory user who appears in the Admin program as an Administrator.
• It is also possible to replace admin with the username and drum with the password of a Calm user. This does not have to be an active directory user—it can be a user created in the Admin program—and it does not have to be a user profile in use at your organisation. This is not secure, though, as this file is stored in plain text.
SecurityRequired: If this is true, Calm security must be enabled (in the Admin program) for users to log in to Axiell Collections. If this is false, any users could log in with any credentials—Calm security will not be set up. For that reason, it is strongly recommended to only set this to false for certain kinds of testing.
Multi-tenancy
In most cases you’ll be using a singular Calm application, which makes the above settings all you need. In the case of an enterprise multi tenancy situation however, 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 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:
10.0
localhost
2143
admin
drum
10.0
localhost
2143
admin
drum
These settings only work with active directory users. Calm application users (created in the Admin program) cannot join these groups.
14. Save the changes in the settings.xml file and close it.
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 unauthorized users from access to certain or all data, because with a singular 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. Security 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 application installed locally on your PC can be accessed in your browser by entering in front of your web application name, for example: .) 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.
3 Updating your Adlib application
If you plan on running Axiell Collections on an existing Adlib application (4.5.1 or older), you’ll have to make that application Collections-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 application and database structure are in good shape: to ensure the future integrity and safety of your data, Axiell Collections is not as forgiving 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 structure 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 transfer to Axiell Collections might be an extra motivation. There are several 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 RemoveTagsFromData.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, for example. These fields you should definitly keep. But of some other newly registered tags you may find that the data they contain 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 RemoveTagsFromDatabase chapter in the Database integrity tools guide which you can download here.
After removing a tag from a database, you can remove the relevant 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 reference.
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 formats which have been specified as a combination of an adapl and a .docx template, and it also supports XSLT stylesheets as output formats. 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 manually. 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 existing Word templates and how to get the new standard Word templates.
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 and store it on the server, a request or freight letter for example, in the selected language, after which the path to the created document is automatically being registered in the Digital document field.
[pic]
This is handled by two after-field adapls: loanproc.ada/bin and tranproc.ada/bin. The adapls use the wordcreatedocument function and the yesno function. Instead of the old .dot templates, the wordcreatedocument function should now address .docx templates while the yesno function doesn’t really work in Collections and just always returns 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 checkboxes 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 using the adapls from the zip file and converting your templates yourself: condition#.dot, condition-in#.dot, condition-objin#.dot, contract#.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 loanproc.ada/bin 4.5.1 and tranproc.ada/bin 4.5.1 that have changed:
• The following variables have been added to the variables declaration:
text templatename[50]
text strippedtime[6], fulltime[8]
integer templatenamelength
• The partial string ‘.doc’ was removed from the string behind docname = everywhere in the code. For example: docname = '_request.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) + ~
'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] = ''
}
return
For the relevant fields, the yesno function in loanproc.ada can present the following questions to users in Adlib for Windows, while in Collections 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. refused/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 being 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 Collections 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 Change locations procedure
Contrary to the Change locations procedure in Adlib for Windows, Axiell 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 executables 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 related records view and a bulk insert option. This is optional, additional functionality which needs to be set up first, simply because it’s highly customizable. Please see the relevant Application configuration options chapters below, for more information.
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 specifications, for example. Therefore the application is highly configurable using 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.
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).
[pic]
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 geographical 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.
[pic]
This functionality is not present in the model Axiell Collections applications prior to version 4.5.2, but any field which contains geographical places can be set up for the geographical map functionality, by making 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 geographical 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.
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.
[pic]
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 recommended) 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 won’t need to create any tables manually: Axiell Collections will automatically do that for you the first time the map functionality is used.
In Settings.xml, (in your Collections\App_Data folder), underneath the node, add the following settings and replace MySQLSERVER by the name of your SQL Server and geolocations by the actual name of the database you created for storing these place names. User name and password only need to be specified if you use SQL Server authentication (instead of Active Directory authentication) to access the database. The different GIS providers each offer their own map layer: if you don’t want certain map layers to be available in the user interface, you can switch them off here by setting to false for the relevant GIS provider. Note that GIS services are not always free to use: if Axiell hosts your Collections application we’ll take care of that of course, but if you install Axiell Collections on your own web server you may have to deal with paid licenses for some GIS services. If you choose not to use a caching database, you must leave out the node and its contents.
SqlServer
MySQLSERVER
geolocations
Google
true
Memory
MapQuest
true
Memory
Microsoft
true
Memory
Yahoo
true
Memory
OpenStreetMap
true
Memory
Custom
true
Memory
2 Setting up the Related records view
The optional Related records view in Axiell Collections provides an alternate overview of all linked records in one or more linked fields, grouped per linked data source, while in the linked data source it provides an overview of all records in the first mentioned data source linking to the current record.
[pic]
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 database 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 relation(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 reversely linked like between Collect and Loans. In principle, the related-records functionality requires only a single-sided setup to display both a forward relation in the current data source (links from the current 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 implemented 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 relations as follows:
[pic]
1. In the Relation texts box on the User interface texts properties tab of the linked field, creator in this example, you specify the forward 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 > creators 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 reverse 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 Objects {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 really 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.
[pic]
4. If the current database (Collect in this example) is also specified as a feedback database in the linked database (People in this example), 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 single-sided linked fields in databases linking to the current database: 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 relevant brief display screen. See the screenshot below for an example 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.
[pic]
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 follows:
[pic]
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 languages 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 really identify the linked record to the user. For example:
[pic]
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 interface languages as are available in your Axiell Collections application.
[pic]
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 current 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 really identify the linked record to the user. For example:
[pic]
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, after which you simply enter your partial (truncation required) or whole search key in the Enter search key box and click the magnifying glass.
[pic]
Besides the full list of indexed fields, you can add a simple search option which can search multiple indexed fields at once. In the screenshot above it's called but you can name it differently if you want.
You must set it up per desired data source in your (.pbk) application definition in the Designer Application browser, as follows:
1. In the tree view on the left, open the data source to which you'd like to add this simple search option.
2. Right-click the Methods list header and select New > Method in the pop-up menu.
3. On the Method properties tab, for Method type, select Simple search.
4. In the Menu texts box enter the name for this new access point which will be visible in the user interface between < and > at the top of the list of indexed fields. Name it Search, for example. Add as many translations as are required by the users of your application.
[pic]
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.
[pic]
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.
4 Configuring the bulk create records option
By default, users have the possibility to create multiple new records with some identical data at once, via the Bulk create one or more records icon in the result set context toolbar (if the user has write access rights).
[pic]
Optionally, you can add a Bulk insert method per applicable data source, to allow you to select which detail screens must be present in the Bulk create window and/or to set additional access right for this functionality. Without this method, all detail screens will be available to the user by default, in the Bulk create window.
[pic]
In Number of records to create the user must always specify the number of identical records to create, while the data he or she enters in the available fields will be stored in all those new records. Data that the user enters in uniquely indexed fields, like Object number in model applications, will automatically be made unique with a sequential number that starts with the value that you set in the Start box at the top of the window. For example, if the user bulk creates three records with object number ABCD-001, while Start has been set to 17, then the automatically generated object numbers will be ABCD-00117, ABCD-00118 and ABCD-00119. (If uniquely indexed fields are automatically numbered fields as well, then automatic numbering takes precedence and no sequential numbers will be added by bulk create.) The Add row below, Remove row, Move field up, Move field down, Edit multilingual fields and Close all panels icons in the window context toolbar have the same function as they do in the context toolbar of the Records details view.
After the records have been created, the user can of course edit them one by one to add data unique to each record.
Add the Bulk insert method as follows:
1. In the data source in the Adlib application definition in which you’d like to have more control over the functionality, add a new method of Method type Bulk insert and add Menu texts in the required languages.
[pic]
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.
5 Adding the Change locations procedure
The Change locations procedure is optional extra functionality for Axiell Collections. This procedure allows the user to change the current location of objects registered in one or more marked records in the result 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 collection 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 application 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 becomes active as soon as you've marked one or more records.)
[pic]
[pic]
A screen will open allowing the user to enter data relevant to this procedure, after which clicking OK will run an adapl program that will be executed for every marked record in the result set, processing the entered data into each record. So the adapl must fill in the new current 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 application 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 parameters for this particular purpose: no need to check the database definition of Collect per se. We called the screen changelocationtask.fmt but any other descriptive name would have been fine too.
[pic]
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 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 detail here about the adapl, it suffices to say that the adapl is structured like an output adapl: it is run for each record separately and therefore has direct read access to all field tags from the processed 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 definition 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
X1 is PARAMETERS_temperrors
fdend
As you can see, the FACS declaration treats the seventeen parameters 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 declaration 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 definition and the data source under which the task must become available, the Internal object catalogue for example (and/or the External object catalogue, the Archives data sources and the Locations and containers data source, when it comes to the Change locations procedure). Right-click the data source and select New > Task in the pop-up menu.
[pic]
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 descriptive 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.)
[pic]
5. Finally, define all used task parameters underneath the Fields header of the new task in the tree view.
[pic]
For each parameter that has no correlating field definition in a database definition somewhere, right-click the Fields header underneath 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 definitions, 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 properties 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 executor 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.
X1 must be a plain text field with length 0: it is only used in the adapl, not on screen.
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 parameters for this task. Then recycle the application pool for Axiell Collections so that the application definition can be reloaded.
The functionality still has some shortcomings:
• Not all errors will be reported, so a manual check of the processed 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 resolved 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.
6 Add a location context column to 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 relevant 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 location (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 information 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 tab, you should see the extra context column showing the upwards hierarchy 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.
[pic]
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 media 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 Collections 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). The fields should be writable, so don’t make them read-only here.
2. If you’d like the new fields to be visible on screens as well, then place them there (near the FN field for example) as repeatable, read-only fields (so that users won’t change the value themselves).
3. 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 retrieve it if you choose to display the field on the Reproductions screen of object records.
4. Since Collections doesn’t know which tags you have used for your new original file name fields, you must add an appropriate configuration to your Axiell Collections settings.xml file, within the node.
SO
SO
The Name attribute must contain the relevant Application ID as specified in the adlib.pbk file. In an enterprise multi-tenancy situation (multiple instances of Collections running under the same web application) this will always be the same ID.
The and nodes can be repeated. The latter comes in handy if a database contains more than one image or application field: the functionality to retrieve original file names applies not only to linked images but to linked documents as well, so you could implement this functionality for digital reference fields too, for example.
• Remember to recycle your Collections application pool after you’ve saved the adjusted settings.xml file.
8 Setting up connect entities
In essence, a connect entity is a user-friendly way to take a field value 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 selection of records to.
[pic]
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.
[pic]
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 underneath 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 object-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 entity.
6. Save your changes and recycle the Axiell Collections application pool.
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 institutions 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 relation, because between names in a pseudonym relationship a hierarchy 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 institutions or when you search a field in another database, linking to Persons 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 pseudonym 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 following icons in the first column of the list on the View table tab of the Find data for the field window:
[pic]
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.
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: Maximum 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 occurrence and Allow the creation of new linked records should be marked; Relation fields Preferred field use, Equivalent field equivalent_name, Broader field part_of, Narrower field parts, Related 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 properties:
[pic]
4. Now you need to set the relation fields for pseudonym and pseudonym_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 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.
[pic]
5. Edit the name.fmt screen and add the pseudonym fields, Pseudonym is a repeated field, Pseudonym for is not repeatable.
[pic]
6. Save all your changes and recycle the Axiell Collections application pool.
10 Image format strings for the Gallery view
By default, the Gallery view in Axiell Collections displays the current record number underneath an image. However, you may set up a format string per image field in the data dictionary to display some other record data instead.
Simply enter a format string of your choice in the Format string option on the Image properties tab of an image field. Below you can see the string %IN% / %VV% / %OB% / %TI% entered in the Format string property of tag FN in Collect.
[pic]
The format string may consist of fixed texts, spaces and field tags in between percent characters. By default the first occurrence will be used.
Other examples of image format strings are:
Title: %TI%
%IN% (obj.no)
%OB% %IN%
When the string to be displayed is longer than three lines, the third line will be cut off with suspension points (…).
[pic]
11 Deep linking to records in Collections
Whatever you do in Collections, the address bar of the browser will always show the same base URL, for example, or something similar. So you can’t save a particular state of Collections as a favorite in your browser.
However, you can use so-called deep linking to address a specific record or search result directly via a URL that you can share via e-mail or which can be offered on a third-party website for users to click on. Normal security applies, so if the user is already logged in to Collections, the relevant search result will be displayed immediately while if the user wasn’t logged in yet, the login dialog will be presented first.
A deep link is created by extending the base URL to your Collections application with a string in one of the following syntaxes:
|/link/ |
|/link//data source> |
|/link/// |
|/link//?query= |
must be replaced by the name of the folder containing the .pbk file of the relevant application
must be replaced by the name of the data source to navigate to, stripped of invalid URL characters ( : # ? / \ % ) and spaces, whilst all registered translations of the name are valid.
must be replaced by a single record number (primary reference) in the designated data source, which must be retrieved.
must be replaced by a URL encoded Collections advanced search. (Look for websites to URL encode any advanced search you may wish to enter, for example.)
Examples:
•
would open application xplus on the Collections Home page.
•
would open the books data source in the library application and retrieve/display all records from that data source.
•
would open the internal object catalogue data source in the xplus application and retrieve/display all records from that data source.
•
would open the books data source in the library application and retrieve/display the record with priref 124.
•
would open the books data source in the library application and retrieve/display all records from that data source.
•
would open the objects data source in the xplus application and execute the advanced search object_number=159. (%3D is the URL encoded = character.)
The user will be prompted to log in if not already logged in. If the user is logged into a different Collections application then he/she will be automatically logged out of that application and logged into the requested one.
12 Storing uploaded Word templates
Axiell Collections 1.3.18262.10 and higher allow custom Word templates uploaded through the Output formats dialog to be stored on the server automatically. The stored template will then become available (initially under its file name) in the Output formats dialog too, so next time this Word template is needed for printing, the user can pick it straight from the Output formats dialog and won’t need to upload it again.
This functionality is optional and is only activated as soon as a correctly configured reports.inf is present in the \data folder of your Adlib application and the corresponding tables in the SQL database have been created. We have a ready-made reports.inf that you may copy to your \data folder, but you will still have to do a little work on it, using Axiell Designer:
1. Download the ready-made reports.inf, two screens and a stripped down .pbk here.
2. After you’ve copied the reports.inf to your \data folder, open it in the Axiell Designer Application browser. On the Database properties tab, change the Data source name and Server properties (and possibly the User name and Password too) to match those of the other database structures. Save the changes to the reports.inf.
3. Right-click the reports database structure (make sure you have selected this one and not one of the other existing database structures) in the tree view on the left and choose Clear database in the pop-up menu. This will create all required SQL tables for the new database and indexes.
4. Now open Windows Explorer and create a new sub folder somewhere in your Adlib application folder to contain all future uploaded templates. In your \Worddoc sub folder you could create a new \uploadedtemplates sub folder, for example.
5. In the Application browser, now select template_id (a1) in the fields list of reports.inf and open the Application field properties tab. Change the Storage path and Retrieval path setting to point to the new folder that you just created and extend that path with /%data%, e.g.: ../Worddoc/uploadedtemplates/%data%
Save your changes to the .inf.
[pic]
6. Recycle the application pool for Axiell Collections.
If you want you can leave it at this, but if you’d also like to be able to manage the list of uploaded templates as it appears in the Output formats dialog (change the visible titles, determine which users should have access to which uploaded templates, hide certain uploaded templates permanently), then you may also set up a data source for this database: each time a template is uploaded, Collections will create a new record for it in the reports database so an appropriate data source in your application structure will allow access to those records. Proceed as follows:
7. Copy the two screens to your \screens sub folder.
8. Copy the adlib.pbk from the zip file to a temporary sub folder directly underneath your Adlib application folder.
9. Open both the temporary sub folder with the copied .pbk and a regular application sub folder with the target .pbk (in \xplus for example) in the Application browser. In the copied .pbk, right-click the Uploaded templates data source and select Copy in the pop-up menu. Now right-click the target application structure node, e.g. Adlib Xplus 4.5.2, and select Paste in the pop-up menu to insert the copied data source into the list of existing data sources. You can still drag the pasted data source to another place in the list. Save the changes in the target .pbk.
[pic]
10. Now remove the temporary sub folder containing the .pbk from the zip file.
11. Recycle the application pool for Axiell Collections.
Once users have uploaded templates during printing, the Uploaded templates data source will now allow you to manage the records associated with those uploaded templates. You will never create new records in here manually, only edit them.
[pic]
A record contains only seven fields, of which you can edit just three:
• Stored template ID – the uploaded template will be saved in the designated storage path under a unique ID.
• Original file name – the original file name of the uploaded template will be saved in this field.
• Visible template name – initially, the original file name will be stored in this field too but you can change it to anything you like. This will be the visible title of the template in the Output formats dialog. It can only be entered in a single language.
• Data source ID – the template can only be visible in the data source from which it was uploaded. The name of that data source will be converted to a unique ID and saved in this field.
• User role/Access rights – the user or role who uploaded the template will automatically get Full access rights. This means two things: this user or role will have Full access rights to this record (so don’t change it to Write, Read or None) and the template will be visible to this user in the Output formats dialog of the relevant data source. If the Default access rights for the application have been set to None, then other users won’t have access to this record and won’t see the template in the Output formats dialog. You can add extra occurrences to this field group to specify access rights for other users/roles: Read, Write or Full access rights will show the template in the Output formats dialog, while Read access rights won’t allow other users to edit this record.
• Category – this field is for possible future use, currently it has no function.
Notes
• Once you delete a record, its associated template will no longer be visible in the Output formats dialog, but the template file itself won’t be removed from the designated storage folder.
• Each time you upload a template with the same file name as an earlier uploaded template (which will happen when you are still perfecting your template), a new record will be created in the reports database and the template file will be stored under a unique name in the designated storage folder. It won’t overwrite the previously uploaded template with the same original file name.
13 Creating output formats for Collections
In Axiell Collections you can export or print data from either the currently displayed record, the currently marked records in the result set or all records in the result set, via the Create a report with a predefined output format icon and the Output formats dialog it opens:
[pic]
Each data source can offer its own predefined output formats. Some default output formats may or may not be present in a data source: four of the 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.
[pic]
The user can also print ad hoc to any custom (.docx) Word template which is located on their own pc or local network (regardless of whether Collections is hosted by Axiell ALM or installed on their local network), via the upload icon next to the Find Word template box. No extra Designer setup required.
When uploading a custom Word template it will currently only be used this once for printing and won't be stored on the Collections server, so next time a user wishes to print to this output format he or she will have to upload it again in the same way.
As predefined output formats, Axiell Collections supports Word templates with the .docx extension, 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 formats. It does not support output adapls using print and output statements to print stuff, nor does it support Word template output formats with the .dot or .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 required.
Word template output formats however, are much more accessible and easier to create 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.
|For experienced Adlib users: template format differences |
|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 relevant |
|differences between the two template types are that for Axiell Collections: |
|the file extension shouldn’t be .dot or .dotx, but .docx: this is simply 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; |
|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 for example, to only print the first occurrence of |
|tag FN; if the specified occurrence doesn’t have data, then nothing will be printed for that field |
|reference; |
|to print all occurrences of a field (regardless of whether the field reference is located in fixed |
|text or in a table) you must not specify an occurrence number, so will print all occurrences|
|of tag VV: each field occurrence will be printed in its own paragraph, so any field label in the |
|same paragraph will be repeated too. |
|you can no longer use tables within tables and you no longer need to because repeated field |
|occurrences in table cells won’t cause their table rows to repeat any more. |
|you cannot use a text box or a frame (like you have around in templates like |
|ObjectDescriptionOneObjectPerPage#.dot, ObjectDescriptionTwoObjectsPerPage#.dot, etc.) to restrict |
|the size of printed images: instead you must use a prefered column width and an exact row height |
|for a table cell to restrict the size of images printed within this cell. The aspect ratio of |
|images will be kept intact and they will be printed within the cell in their entirety; |
|label templates aren’t supported by Axiell Collections, but if your label sheets consist of just a |
|single column of labels, you can simulate a label template by creating a normal template with a |
|single cell table (with the position and the dimensions – exact row height – of a single label plus|
|the empty line beneath it) at the top of the page. Of fields you should only print the first |
|occurrence and you should make sure that a field value never wraps to the next line by applying a |
|small font or via adapl preprocessing of such field values. |
|the notation to print thumbnails is not supported yet; |
|e-mail parameters are not recognized yet, so you shouldn’t use them (although they won’t spoil your|
|printout either). |
|the parameter is supported, but causes a page break exactly where the parameter is |
|placed in the template, so just always place it at the bottom. Templates which do not contain the |
| parameter nor a table with the and |
|parameters (which are also supported) print processed records directly below each other; |
|you can use Word document “sections” for more complex documents: 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 format 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 applications 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 Internal 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 document in Word, by right-clicking the table cell and selecting Table properties in |
|the pop-up menu. |
|Image |
|Object no. |
|Object name |
|Creator |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|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 original 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 |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|Example 3: images will have a fixed maximum width and height and only the first occurrence of each |
|field will be printed. Check the properties of the FN table cell by right-clicking it and selecting|
|Table properties in the pop-up menu. Each record will be printed on its own page. |
| |
| |
|Object no.: |
|Object name: |
|Creator: |
|Title: |
|Dating: to |
|Location: |
| |
| |
|___________________________ |
| |
| |
| |
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 software. 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 according to their fixed text language.) Save you additions and changes to this template regularly.
[pic]
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 Collections or Adlib), this text will automatically appear in the generated document.
3. If you wish to output data and/or images from your database records 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 template, type the field name (use only the English field names) or tag of the field between double angle brackets, and type these exactly as they have been defined in the data dictionary of the current database. (You can only include fields from the current database, plus merged-in target fields that come with linked fields, in a template.) Field names and tags are case-sensitive, so use or . (Tags starting with % are also allowed.) Use any desired font or font size because record data will be added in the same font.
It is possible to print only a specific occurrence or to print all occurrences 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 language 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 dictionary field name and IN the field tag. You can choose which to use.
[pic]
Naming conventions for templates
Microsoft Word templates which are available as predefined output formats in Collections, are interface 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.)
Word templates (either used as predefined or ad hoc uploaded output formats) are also data language dependent: this 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 current 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 to be used as predefined output formats, interface language dependency means that you have to create a separate template for each interface language in which users may want to work; this does not apply to Word templates which will be uploaded ad hoc by users themselves.
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 have at least a Dutch template and an English template for each print task.
Axiell Collections recognizes the language of a template by the number 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 following example:
To:
Axiell ALM Netherlands BV
Safariweg 18-22
3605 MA Maarssen
Re: new service pack
Dear Sir/Madam ,
We enclose information about the release of our new service pack, in which some major improvements have been made.
We trust this has provided you with sufficient information,
The Axiell Helpdesk
Word will repeat this text for every record you export to this template, and will replace the field references with data from the processed record. 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 instructions to Word.) In this case, you should place the parameter 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 others 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 occurrences of a repeatable field are printed by default, if you do not specify an occurrence number. This applies to field references in both letters and record 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, although 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 repeated field group in a list: fields from the Dimensions field group on the Physicial characteristics screen tab of an object record, for example. In such case we typically like to print all occurrences of the repeated 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 multiple records to 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 parameters in the rows just above and just beneath the references, to indicate 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:
|First column header |Second column header |etc |
| | | |
| | |etc |
| | | |
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 |
| | | |
| | | |
| | | |
In this case, the table prints all occurrences of the fields underneath each other in separate paragraphs, but within a single cell. So two records, 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 |
| | | |
| | | |
| | | |
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 limitation 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 . The parameter should be placed immediately above the row of field references. Only the first row of the four is optional, in which you can enter fixed texts to serve as column headers.
The rows in which records will be printed, can be numbered sequentially if you want. You can achieve this by inserting an automatic number 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 record 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 Borders and shading, through the Table properties (see your Word manual 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 records separately from the relevant databases to the different templates.
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: .
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 specification (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 IMAGE, the URL or path itself will be printed, instead of the image.) |
|Database fields of the APPLICATION type (e.g. Identifier in library applications) can refer to |
|images, amongst others, but these images cannot be printed to Word. |
1 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 allows).
2 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:
| |Object no.: |
| |Object name: |
| |Maker: |
| |Title: |
| |Date: |
| |Location: |
| | |
| | |
| | |
[pic]
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 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 following symbols: * $ % + - . and /. Code 128 on the other hand, is able to convert all 128 characters of ASCII, but this font type is currently 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 inline. An object number field reference for example:
It may differ per font to which part of the field reference the barcode font must be applied, so you may need to experiment a little. In our test, if the field reference was in its own paragraph, we had to select the whole paragraph and apply the barcode font to it from the Font drop-down list in the MS Word Start menu. For example:
[pic]
If the field reference was placed inline, we selected the whole field reference and applied the barcode font. For example:
[pic]
Enlarge the font size to obtain a properly sized barcode. The > characters themselves won’t be converted or printed when you use a code 39 barcode font.
To print a human-readable version of the object number as well, simply insert in a normal font underneath the converted field reference.
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.
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, for example to print the English value of the second occurrence of tag OB. Both arguments are optional: you may specify just an occurrence or only a language code or neither, like .
1 Examples
Below you’ll find some examples to clarify things. Suppose you’re using 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 drop-down in the top toolbar if you have a multilingual data application.
Then assume you have a record containing two object names and a title 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 Harderwijk, 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 value. (The four table cells automatically print all occurrences.)
|Example template |
|Tag OB: |
|Tag OB[2]: |
|Tag OB[fr-FR]: |
|Tag OB[2,en-GB]: |
|Field object_name[1,fr-FR]: |
| |
| |
| |
| |
| |
| |
|Tag TI: |
|Field title[1]: |
|Tag TI [fr-FR]: |
|Tag TI [1,en-GB]: |
|Field title[1,nl-NL]: |
| |
| |
| |
| |
| |
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 |
| |
| |
|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 Grolsteeg 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 available:
• Every new record is printed on a new page. Do not use this command in labels or in a template containing a record list.
• and Use these parameters to create a record list with a table. (Cannot be used together with .)
Using a label printer
If your (continuous-feed) label printer supports it (tested okay on a Zebra TLP 2844-Z and Intermec PM43 printer), you can in principle print Word documents to it, containing even images (printed in black and white) and/or barcodes. This allows you to create a label-sized Word template to print record data to. You can have it used as an ad hoc template or set it up as an output format like any other predefined output format for a normal Word template.
- The challenging match between Word document properties and printing preferences
For printing from within Word it's important that your template page size matches the label page size as set up in the printer's printing preferences, as well as the page's orientation in both configurations. If those don't match, Word will prevent you from laying out your label template as you like: it will automatically change margins and such and will generate several warnings about non-matching page sizes and margins when you actually try printing to such a template. No problem you'd think, but there's a snag: there's a longstanding issue which prevents you from printing from within Word in the printer's portrait mode (horizontally printed text) when the labels are wider than they are high (as the labels in the image below) and likewise prevents you from printing in the printer's landscap mode (text printed sideways) when the labels are taller than they are wide.
[pic]
When designing your Word label template you'll find that when you set the page height to match the label's height and the page width to match the label's width, Word automatically adjusts the setting of the page's orientation to landscape if the label is wider than it is high or to portrait if the label is taller than it is wide: so Word is talking about the page's orientation. Your printer however, appears to interpret its orientation setting as pertaining to the text on the label (no matter the height and width of the label), where portrait means horizontally printed text and landscape sideways printed text. During the design phase and during printing this causes problems because Word expects the printer's orientation to mean the same thing as its own page orientation. And thus Word finds that the height, width and margins don't match and won't allow you to lay out your template as you'd like to and/or it generates several warnings and prints data and text in the wrong place on the label.
Luckily there's a work-around, but as work-arounds go it's a slightly awkward one...
- Changing the printer's printing preferences
[pic]
For labels that are wider than they are high, whilst you'd like to print horizontally to them, the solution is that in the printer's Printing preferences (Control panel > Devices and printers, right-click your label printer and select Printing preferences) you change the height of the label to a value somewhat bigger than the width. So if the Width on the Options tab is 10.2 cm, you change the Height to something like 10.5 cm and leave the Width and portrait setting as they are. The point is that this will allows us to create a Word template in portrait orientation as well, while still being able to print horizontally and have matching page dimensions. By the way: the page size you set here in the Printing preferences doesn't seem to have any negative impact on other printing actions to this printer (as far as our testing showed), so there should be no harm in these adjustments and otherwise you can always (temporarily) restore the page height to its original setting.
- Creating the Word template
[pic]
In principle, the idea is that you create a normal .docx template with a page size that matches the actual label size that your printer uses (as should have been set up properly in the printer's Printing preferences). Only when the issue described in the paragraphs above applies to your situation and you've fixed it by adjusting the label height in the Printing preferences, you must create a .docx template with a page size that matches the label size as set up in the printer's Printing preferences, regardless the actual size of the physical labels.
So match the page size of your .docx template to the size of the Printing preferences page Width and Height: in Word go to Size > More paper sizes in the Layout ribbon and on the Paper tab set the Page size to Custom size and change the Width and Height accordingly. On the Margins tab you'll see that the Orientation is now Portrait, as we wanted it to be. You can change the margins to your liking.
You can fill your template normally with field references, fixed text, a logo maybe, a table cell with an image reference and/or a barcode field reference as described in the previous paragraphs. Use a parameter to make sure that each record will be printed on a separate label. Of course, do remember that the physical labels are not as tall as your current template would suggest, so only fill the upper part of your template with field references and any other content: you don't want the contents to spill over to the next printed label. The vertical ruler on the left gives an indication of the vertical space your field references occupy.
- Printing from within Collections and Word
[pic]
When "printing" to this template from within Collections, the resulting Word document will first be opened in Word where you can still edit it if necessary. Actual printing to the printer must be done from within Word, in which case you must of course select your label printer to print to, otherwise your printout will go to the default printer.
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.
[pic]
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 application to be available to users. Make sure the title describes the output format clearly.
[pic]
3. Behind the Template path property, click the … button to locate your new template.
[pic]
To find your .docx template in the proper folder, set the drop-down list in the right bottom corner to All files (*.*) first, otherwise the .docx files won’t be listed. Select one of the translations of the template you made: it doesn’t matter which.
[pic]
[pic]
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:
[pic]
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 application definition.
6. Recycle the Axiell Collections application pool in IIS so that Collections 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 Collections, you don’t need to recycle the application pool again: Collections 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 Axiell Collections website in your browser list of trusted applications or switch off pop-up blocking via your browser’s settings.
14 Setting up an IIIF image server
The processing of images retrieved by the Media Viewer can be handled in two ways:
- by the browser: this requires no extra setup and is expressed in the Collections settings.xml file by the following default section:
Browser
- by IIIF image processing: the International Image Interoperability Framework (IIIF aka triple-IF) defines several APIs that, amongst others, provide a standardised method of describing and delivering images over the web. Depending on whether the processed images have been made IIIF compliant or not, using this functionality offers several advantages over browser processing of images, but both offer the possibility of deep zooming: although your images contain a fixed amount of information, algorithms can sharpen a picture and enhance its contrast just before display, also allowing you to zoom in further without losing too much detail. The IIIF media viewer in Collections offers a slightly different interface than the normal media viewer, offering a more fluent zooming experience.
A substantial performance improvement during the loading of high resolution images can be achieved if IIIF compliant images, so-called pyramidal tiled .tiff files, are used because it retrieves much less information than contained in the original image file. This is possible because when an image is converted to a pyramidal tiled .tiff file (which requires a special, internal Axiell tool) it is not only converted to several smaller resolution versions of the entire image (which will be retrieved when users view the entire image) but each of those resolution layers (forming a pyramid) is divided up in tiles as well so that zooming in to a particular part of an image only requires retrieving that particular tile. This also means that with IIIF compliant images you don’t need to worry about the file size of high resolution images slowing down performance of Collections, since the IIIF API only retrieves the part of the image it needs and in the resolution that is currently required.
IIIF image processing and the optional bulk conversion of your existing images to IIIF compliant pyramidal tiled tiffs may involve additional licensing fees and conversion costs. Please consult our Sales department for information about options and pricing. Note that currently no automatic conversion to IIIF compliant pyramidal tiled tiffs is available in Collections, so normal images that are linked to records won’t be converted.
Setting up the IIIF functionality
1. Place the IIIF image server files on the web server which stores the (converted or normal) images themselves.
[pic]
2. In the Collections settings.xml file replace the default Browser viewer by IIIF and uncomment (or add) an node in which {localhost} must be replaced by the actual server name containing the Axiell IIIF image server files, for example:
IIIF
iipsrv.fcgi
3. Open IIS. Select the Default Web Site and click Basic Settings… under Actions. Check the Application pool.
[pic]
Close the Edit Site window, select Application Pools under Connections, select the application pool used for the default website and click Advanced Settings… under Actions. Look up the (Process model) Identity. The identity specified here should have access to the server containing the \images folder. The image server will use this identity, so specify an appropriate user and application pool for the default website.
4. With the Default Web Site selected, double-click the Authentication icon.
[pic]
Then select Anonymous Authentication and click Edit under Actions. By default the Anonymous user identity is set to a Specific user (IUSR): make sure to set the Anonymous user identity to Application pool identity. Click OK.
[pic]
Underneath the defaul website, add a virtual directory called imageserver (that we already set in the ) for the IIIF image server \virtual-directory subfolder.
[pic]
5. In IIS, add another virtual directory for your main images folder, with for example Alias: ModelApplication and as Physical path the actual path to the \images subfolder of your Axiell/Adlib system.
6. In IIS, select the main Connections node on the left and double-click the FastCGI Settings icon in the middle window pane.
[pic]
(If the icon isn’t present, you’ll have to turn the CGI Windows feature on first via the Control Panel (select Programs > Turn Windows features on or off – Internet Information Services > World Wide Web Services > Application Development Features – and mark the CGI checkbox, but this may vary per Windows version.)
7. Then click Add application in the right IIS window pane, under Actions. For the Full Path option in the Add FastCGI Application window, look up the path to iipsrv.exe, one of the IIIF image server files that you placed on your web server in step 1, via the … button.
[pic]
8. Put the cursor in the field behind Environment Variables and click the … button.
[pic]
Add the following members:
[pic]
with the following values:
- FILESYSTEM_PREFIX: the path to your images subfolder, C:\Collections\Model application 4.5\images/ for example;
- Verbosity: a number between 0 and 10 which determines how much the server should log;
- VIRTUALPATH: the URL to the virtual directory for your images folder, something like
- LOGFILE (optional): a path to a log file, C:\Ourweb\ImageServer\virtual-directory\Logs\log.txt for example.
Click OK twice to close both windows.
9. Go back to the Default Web Site in IIS and double-click the Handler Mappings icon.
[pic]
Then click Add Module Mapping, under Actions.
10. Fill in the Add Module Mapping dialog as follows, but select your own path to the iipsrv.exe file in your IIIF image server folder. Click OK to close the window: you’ll have to confirm your action.
[pic]
11. Now select your new imageserver module mapping in the list of Handler Mappings (probably all the way at the bottom) and click Edit Feature Permissions under Actions. Mark the Execute checkbox so that all checkboxes are marked and click OK.
[pic]
12. This should conclude the installation of the IIIF server and you may close IIS. To test if the server is working correctly, open a browser and enter a URL similar to the following (replace localhost by the name of your web server and 103.jpg by the file name of an existing image in your \images subfolder): If the browser displays a valid json response, then the IIIF server has been installed correctly. For example:
[pic]
If you get a single message stating that is not a regular file and no glob support enabled, you should check the application pool identity and its access rights to the server containing the \images folder again.
If the JSON data displays alright, but clicking the link gives an HTTP Error 401.3 – Unauthorized, it might be that IIS users have no access to the server on which your \images folder is located. In this case Axiell Collections won’t show any images in the Media Viewer.
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.
[pic]
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 server.
[pic]
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.
[pic]
4. Type “Web deploy” in the search box in the right upper corner of the Web platform installer and press Enter.
[pic]
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 available in the right-click pop-up menu for an application.
[pic]
[pic][pic]
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.