Explainer: User Symbolics

Learn how to calculate and manipulate data in Vernon CMS with User Symbolics. You can use this powerful functionality to change how information is displayed in Reporting, List Manager, and Vernon Browser. Grab your magic wand and learn the incantations that will transform your data!

How User Symbolics can help you

User Symbolics (or user-created symbolic fields) perform an immediate calculation on your data to do a variety of tasks. You can create an unlimited number of these symbolic or calculated fields in any of the major files in Vernon.

You can create User Symbolics to do the following tasks:

• Pull information from related fields into a file to make it easier to report on.
• Extract specific rows of information from one table of a record.
• Perform basic maths or calculations.
• Generate static data that’s the same for every record in a report.
• Reformat information for presentation in another system, including our Vernon Browser online collection module.

You can then select your User Symbolic fields in Reporting and List Manager. These fields are always at the bottom of the Available Fields list.

You’ll need to have supervisor access in Vernon CMS to create User Symbolics. We almost always help our clients set them up. Email support@vernonsystems.com with your enquiry.

Video: Webinar on User Symbolics

Steps to create a simple User Symbolic

First, let’s look at the basic steps to creating a simple symbolic.

1. Go to Tools > System Maintenance > User Defined Parameters > User Symbolics.
2. Select the file.
3. Click the New button.
4. Enter a name for the symbolic.
5. Enter the file that the data is stored in.
6. Enter the field to report.
7. Enter the link field.
8. Test the symbolic.
9. Save the symbolic.

Here are some examples of things you can do with simple symbolics.

Get related data

You can create a simple User Symbolic to pull information from a record that’s related to an object. We’ll create three examples:

• A field that shows the address of a person associated with an object.
• A field that shows only the authority term of Material term instead of the whole hierarchy.
• A field that shows the common name of a specimen.

Example 1: Associated Person Display Address

Let’s make a symbolic that shows the address of a person associated with an object.

1. In the User Symbolic window, for the File, select Object.
2. Click the New button.
3. In Symbolic Name, enter Associated Person Address Display. That’s the label that will display in Reporting and in List Manager.
4. Make sure that Simple Symbolic is selected.
5. In Data Stored In, enter Person.
6. In Field to Report, enter Address Display.
7. In Link Field, enter Associated Person.

Now we can test the symbolic by entering a record into the Sample Record field. This field works as a simple search. We can enter the accession number of a record and press Enter. Then when we click the Calculate button, we’ll see the results.

The last step is to save your hard work!

Example 2: Material – Simple Name

In our next example, let’s make a symbolic that displays just the authority term name for Medium/Material term, rather than the full hierarchy.

Our demo system uses the Art & Architecture Thesaurus which has a very detailed material keyword hierarchy. So, for the term ceramic, the field displays the following hierarchy:

ceramic/<ceramic and ceramic products>/<clay products>/<clay and clay products>

We want to create a field that shows just ceramic so that it’s more usable in a report. The Conversion field in the User Symbolic allows us to specify the exact display text that we want.

Here we go:

1. In the User Symbolic window, for the File, select Object.
2. Click the New button.
3. In Symbolic Name, enter Material – Simple Name.
4. Make sure that Simple Symbolic is selected.
5. In Data Stored In, enter Object.
6. In Field to Report, enter Media/Materials. The Link Field will then automatically contain System ID, and the Conversion field will automatically contain [AU_CONV,MATERIAL].
7. Edit the Conversion field by inserting *AU_NAME so that it reads:
    [AU_CONV,MATERIAL*AU_NAME]
8. Test the symbolic.
9. Click Save.

Our symbolic got the data from the current record using the ID. Then we overrode what we call the ‘output conversion’. Vernon has a link to that Material authority term using the ID of the material.

The Conversion field contains a little bit of code that tells Vernon to do an authority file conversion using records in the Material file. And we overrode those options to pick a different display field. We told Vernon that instead of using the hierarchy, which is the default display, just use the authority term name, which is the field AU_NAME.

Example 3: Classification – Long Name

In this example, we’ll pull in a very specific piece of related information from a related authority record.

Our demo system includes natural science specimens, kindly given to us as sample catalogue records from Queensland Museum.

Here’s one of our bee fly records. In the Classification field, it has a Linnean (or natural science) Latin classification of tutela/Comptosia. If we publish this information to Vernon Browser, most people looking at the online collection wouldn’t understand what that means.

If we go to the related Classification authority term record, we can see that a long or common name has been recorded: Bee fly.

So the term Bee fly is not recorded directly in the Object record, but in the related Classification record. Let’s create a symbolic that pulls in that related long name.

1. In the User Symbolic window, for the File, select Object.
2. Click the New button.
3. In Symbolic Name, enter Classification – Long Name.
4. Make sure that Simple Symbolic is selected.
5. In Data Stored In, enter Classification.
6. In Field to Report, enter Long Name.
7. In Link Field, enter Classification.
8. Test the symbolic.
9. Click Save.

Steps to create a complex User Symbolic

We’ve looked at simple symbolics where we take data that’s already stored in Vernon and just pull it into a different place, and maybe do some minor reformatting. We can also use what we call complex symbolics which run some kind of code to manipulate the data in further ways.

Let’s look at the basic steps to create a complex symbolic.

1. Go to Tools > System Maintenance > User Defined Parameters > User Symbolics.
2. Select the file.
3. Click the New button.
4. Enter a name for the symbolic.
5. Select Complex Symbolic.
6. Enter the Subroutine Name.
7. Enter the Subroutine Argument.
8. Test the symbolic.
9. Save the symbolic.

Now let’s look at some examples.

Extract a row from a table

You can extract specific rows of data from tables with a complex User Symbolic.

Let’s say you want to include the design number of objects in a report. In this example, Design Number is a term in Other ID Type. By default, you can only report on all Other IDs and Other ID Types, not specific ones.

So let’s create a symbolic which extracts just Design Number and makes it available in the Reporting tool.

Before we begin

There’s a couple of things we need to do first.

Get the System ID of the term we want
In the Other ID Type field, click Options and select Show IDs. The System ID for Design Number is DN.

Get the internal fieldnames of the fields we want
Click into any field in the Other ID table  and press Alt+F1 on your keyboard. The internal fieldnames will show in the Database Information window. The internal fieldname for Other ID is OTHER_ID, and for Other ID Type it’s OTHER_ID_TYPE.

Create the complex symbolic

• File: Object
• Name: Design Number
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: EXTRACT.AMV!OTHER_ID_TYPE;DN!OTHER_ID

How the argument is constructed

Let’s take a closer look at this argument. Each part of the argument is separated by an exclamation mark.

• EXTRACT.AMV
  The first part of the argument tells Vernon which argument we are using. AMV stands for Associated Multi-Values. That’s another way of referring to a table. For example, the column Other ID is always associated with Other ID Type.
• OTHER_ID_TYPE;DN
  The second part of the argument tells Vernon which field and term to look in. That is, the field OTHER_ID_TYPE and the term DN (the System ID for Design Number).
• OTHER_ID
  The third part of the argument tells Vernon what data to display.

Join fields together

We can also combine multiple fields together to make one new reformatted set of information. A typical example would be to join the Artist and the Role fields together. You might want to output that to some other system like Excel that can’t cope with the concept of multiple repeating entries. In Excel, each record is just a single row, and you can’t have embedded cells within a single row.

So you might choose to reformat the Artist and Role information to already be joined together in a tidy display before it ever gets out of the system.

Let’s look at how to create this symbolic.

Before we begin

As we did in the previous symbolic, let’s get the internal fieldnames of the fields we want.

Click into the Artist/Maker field and press Alt+F1 on your keyboard. The internal fieldnames will show in the Database Information window. The internal fieldname for Artist/Maker is PROD_PRI_PERSON, and for Role it’s PROD_PRI_ROLE.

Create the complex symbolic

• File: Object
• Name: Artist and Role
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: MULTI.FIELDS!PROD_PRI_PERSON!PRO_PRI_ROLE! – !CR/LF!1

How the argument is constructed

Let’s analyse this argument. Remember, each part of the argument is separated by an exclamation mark.

• MULTI.FIELDS
  The first part of the argument tells Vernon which argument we are using. MULTI.FIELDS is the argument for joining two or more fields together into one field.
• PROD_PRI_PERSON;PRO_PRI_ROLE
  The second part of the argument tells Vernon which fields to display. These are separated with semi-colons.
•  –
  The next part of the argument is the punctuation that should separate the fields. In this case, it’s a space, a hyphen, and another space.
• CR/LF
  This code stands for Carriage Return / Line Feed and it tells Vernon to enter a line break.
• 1
  The last part of the argument is a flag for associated multi-value fields. That is, the fields that appear together in the same table. The AMV flag is set to 1, which means the values will be displayed by row. For example:
  Bill Culbert – Artist
  Ralph Hotere – Artist

Count values in a field

You can create a complex symbolic to do simple maths, such as a total on a field.

You might want to identify all the records where multiple makers were involved. For example, a publication that has an author and illustrator.

Create the complex symbolic

• File: Object
• Name: Artist Count
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: VALUE.COUNT!PROD_PRI_PERSON!VM

How the argument is constructed

Let’s look at the three parts of this argument, which are separated by exclamation marks.

• VALUE.COUNT
  The first part of the argument tells Vernon which argument we are using. VALUE.COUNT is the argument for counting values, or the number of entries, in fields and tables.
• PROD_PRI_PERSON
  The second part of the argument is the field we want to count values in.
• VM
  The last part of the argument is what we want to count. VM means value marks or rows. TM means text marks or paragraphs.

Search on the symbolic

You can search and report on any symbolic that you create. In this example, you could write a Select Statement to find all records that have multiple makers.

Every symbolic has its own permanent internal fieldname. Our Artist Count symbolic is USER_SYM_39.

So let’s create that Select Statement.

1. Open Advanced Search on the Object file.
2. Click Select Statement.
3. Enter the following statement, then press Enter:
   WITH USER_SYM_39 > 1
   This means Vernon will find objects where the Artist Count is greater than one.
4. Click Next to see the number of results.
5. Click Finish to open a browse list of the objects.

Get one level of a hierarchy

We can create a complex User Symbolic to pull out just one level of a hierarchy within a term field. A good example of this is the Place field.

Most of the time, you’ll be as specific as possible with production place. You’ll try to catalogue the town, city, or state, as well as the country. In this example record, the Place field contains the city (New York), the state (New York), and the country (United States of America).

However, sometimes you’ll just want to reference the country, such as in a report or in List Manager. So let’s create a symbolic field that pulls out just the production country.

Create the complex symbolic

• File: Object
• Name: Production Country
• Subroutine name: AU_USER_SYM_HIERARCHY
• Subroutine argument: 72!0!PLACE!NA!!ID
• Conversion: [AU_CONV,PLACE*AU_NAME]

How the argument is constructed

Let’s look at this argument in detail. An exclamation mark separates each part.

• 72
  The first part of the argument is the Field Mark Count (FMC) of the field to extract authority terms from. You can find it by pressing Alt+F1 in a field to open the Database Information window. In this example, 72 is the FMC of Place Made.
• 0
  The second part of the argument is for multi-value authority fields. Setting it as 0 (zero) tells Vernon to only process the first authority term in the table.
• PLACE
  The third part of the argument is the System ID of the authority file.
• NA
  The fourth part of the argument tells Vernon how far up the hierarchy to go. We’ve set that as NA which is the System ID for Nation.
• 
  The fifth part of the argument is the ‘limit’ parameter and tells Vernon which level of the hierarchy to stop at. We don’t need it in this case, so we’ll leave it blank.
• ID
  The sixth part of the argument is the data we want to pull out. So we’re pulling the name of the term.

Now we’ve got a field that for any object record, Vernon will traverse up that hierarchy until it finds the level of Nation and then display just the name of that country. That field is available as something that we could search on, and something that we could sort on as well. So within List Manager, you might sort all of your records so they’re ordered by Production Country.

Vernon Browser symbolics

One of the most common uses of complex User Symbolics is for output to our online collection product, Vernon Browser. Often you’ll want to change the presentation of information or pull in details from other files for presentation on the online collection site.

Let’s look at examples from specific online collection sites and then we can see how they’ve been set up as User Symbolic.

Create a credit line

As part of MOTAT Museum of Transport and Technology’s online collection, they have a credit line field. Vernon has a credit line field where you can manually enter credit lines. But MOTAT needed to automatically generate a standard piece of credit line text. For them, that’s the object name, the accession number, and the name of their organisation. And so we can see those three things joined together on this tram shelter sign record on the MOTAT website.

Ideally you don’t want to manually enter that into the credit line field of every catalogue record. That’s repetitious and time-consuming, but it’s also problematic if other information changes at any point. For instance, if somebody fixed a typing mistake in the Name field, they’d have to remember to also do that in the credit line.

So rather than entering that information in the credit line field, MOTAT has a User Symbolic that uses the MULTI.FIELDS option to take three different fields and join that information together.

We’re doing two things to make that possible.

Firstly, the organisation name is going to be the same in every credit line. There is a User Symbolic argument called FIXED.LITERAL which adds a block of text which will be the same for every single record whenever you make use of that field. In this example, we’ll create a FIXED.LITERAL symbolic which shows our company name, Vernon Systems Limited.

• File: Object
• Name: Vernon Systems Limited – Text.
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: FIXED.LITERAL!Vernon Systems Limited

Secondly, we can then join that symbolic field, USER_SYM_41, with the object name and accession number by using the MULTI.FIELDS option.

• File: Object
• Name: Vernon Systems Limited Credit Line
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: MULTI.FIELDS!NAME;ACCESSION_NO;USER_SYM_41!, !

As you can see in this example, symbolic fields can be stacked together over time. You might manipulate a piece of information with one User Symbolic and then you might reference that symbolic later in an even more complex example.

This symbolic automatically generates the credit line from the fields and it’s live. Vernon’s not storing that information, it recalculates it whenever the symbolic is used. So that information’s always going to be correct even if things like the name get edited at a later point.

Create clickable links

As part of your cataloguing information, you might record external web pages as useful reference material for a particular object or person.

On our Vernon Browser demonstration site, we’ve got A Colour Box, a film that was made by the New Zealand artist Len Lye. As part of that record there are two clickable links.

Here’s the Object record in Vernon CMS, on the Document References window.

Within any of our major files you can record links to external files or web pages through the Document References window. Here’s that information that Vernon Browser was relying on.

The External File column has the web URL (or web address). The Notes column has been used to create the display text that the end visitor will see on that web page. Often web URLs aren’t human-readable, and we’ve used the Notes field in this table to create a human-readable piece of text to go with that URL.

Lastly, this table might be used for a range of different references, not all of which are publicly accessible. You might have links to acquisition documents for instance which are internal PDF or Word documents.

And so we’ll use the EXTRACT.AMV option to extract only the rows from this table where the Category is Public Web Link. That’s like the concept that we used earlier of Other ID. We’re looking for rows where there’s a particular System ID in the Category file. In this case, the System ID for the category Public Web Link is 1.

We also need the internal fieldnames. For External File it’s DDE_FILENAME, for Category it’s DDE_CATEGORY, and for Notes it’s DDE_NOTES.  

Firstly, we want to pull out all the URLs, and so that’s using the same EXTRACT.AMV option that we saw before. And like Other ID, it’s simply a case of saying what field are we filtering on. So we’re filtering on the Category column all things which were System ID 1, which is Public Web Links. And if it’s found, display the filename.

• File: Object
• Name: Public Web URLs.
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: EXTRACT.AMV!DDE_CATEGORY;1!DDE_FILENAME

Secondly, let’s use the same concept to pull out the Notes column.

• File: Object
• Name: Public Web URL Text.
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: EXTRACT.AMV!DDE_CATEGORY;1!DDE_NOTES

And then lastly let’s use the MULTI.FIELDS option to join all that information together.

• File: Object
• Name: Public Web URL Links.
• Subroutine name: USER_SYM_SUBROUTINE
• Subroutine argument: MULTI.FIELDS!USER_SYM_28;USER_SYM_29!|!CR/LF!1

This symbolic creates a combined field with the URL, a vertical bar, and then the notes. This is a standard format that Vernon Browser supports for links that include associated text.

Create a description for a Google Maps pin

Vernon CMS can export data to Google Maps. You can record a map reference, which is a latitude-longitude position, in the Object > Field Collection window. Google Maps expects a name field, a description field, and a position as part of the data for plotting that on the map.

You might not necessarily have one single description field which is useful on the map. So you may want to use the MULTI.FIELDS option to combine together several pieces of information for displaying that on each map pin.

Contact support@vernonsystems.com and we can help you set this up.

Publish 3D, audio, or video content

As well as publishing clickable links that are stored in the Document References window, you can also publish rich content such as 3D models, audio files, or videos.

First, record the URL (or web address) of a 3D, audio, or video file in the External File table of the Document References window. Then create a category of external file with a relevant label, such as Sketchfab. We can then configure Vernon Browser to display the file in an embedded player.

Here’s a Sketchfab model of an albatross on the Puke Ariki website.

Media providers that work with Vernon Browser include:

• Sketchfab
• YouTube
• Vimeo
• Soundcloud

Contact support@vernonsystems.com and we can help you set this up.

Resources

• Learn more about User Symbolics (Vernon CMS Help website)
• Watch the User Symbolics Webinar (YouTube)