K-fields

Reporting > Report Helpers > Fields > K-fields

A K-field is a field whose value is the result of a JavaScript functions calculation with access to other fields in the record, organizational hierarchies, and lookup tables. Any change in a field referenced by the calculation automatically updates the K-field value.

For example, a company may have three different surveys with a different Likelihood to recommend (LTR) question for each program, and wants to see these three questions rolled together into a single LTR metric in Reports and Exports. This can be accomplished by creating a K-field that returns the appropriate LTR Feedback field for each survey. This K-field can then be added to Reports and Exports.

Because K-fields are calculations applied to a particular record, they can be used in most places where record-level fields are allowed. Some common uses include:

Standard reports — Displaying the results of the K-field calculation in various parts of reports.
Exports — Including calculations in exported data.
Alerts — Constituting the conditions to generate Alerts or to concatenate emails for Alert notification recipients.
Sampling — Act as survey conditions for sample filters.

K-fields are virtual survey questions (non-aggregated). Like normal survey questions, K-fields must have an Alternative set associated with it. The logic for the K-field is written in JavaScript and must return an appropriate value for the Alternative set selected.

See these topics for more information about working with K-fields:

Warning: In a K-field's code, do not reference the same K-field. When executing such a circular reference, it consumes resources, eventually stops processing for the company instance, and produces an event ticket.

Aside from being a really bad programming practice, if you do this, other people using your instance — and the rest of your company — might be mildly upset with you to the point where you may be forced to provide donuts to your entire team daily for up to one year. Just don't do it.

Properties

Label

Label is a globally unique variable within Experience Cloud and should start with the company name to ensure that it is unique across all Medallia instances. This cannot be changed once saved.

The value must be lowercase English letters, numbers or an underscore, and must start with a letter.

Name

Name of the K-field that appears in reports. This can be changed at any time. The value must be lowercase English letters, numbers or an underscore, and must start with a letter.

Restriction: Name can have a maximum of 63 characters.

Category (optional)

Groups all definitions with the same Category value together, which can make them easier to find on the list. Definitions are ordered by Priority inside each category. Definitions with no Category value are listed underneath. Use the filter above the list to see just the definitions of the selected category.

The act of assigning a definition to a category that doesn't exist creates a new category. Note that category names are case sensitive.

Note: To delete or change the name of a Category, simply change the Category value in each of the definitions that belongs to it.

Priority

Priority specifies the order in which the fields appear in the list of K-fields.

Description

An optional field to describe the K-field and its purpose.

Multi Valued

Checking the Multi Valued box returns an array in place of single value. To combine several values into an array, the list() function can be used.

Important: Multi-valued fields must be Backfill or Export only.

Slug Availability

SlugAvailability dictates if and when a K-field gets added to Slug. Try to use Export only whenever possible, as this limits the number of K-fields which get added to Slug, which can significantly reduce backfill times.

Available — Calculates this K-field immediately upon saving it for all existing records, and for new records as they enter Experience Cloud. However, the K-field value for existing records are only recalculated when the K-field calculation is updated in a material way (modifying blank lines or adding/removing comments does not count), the survey is updated, a backfill is run, or there is a deployment that causes a cache rebuild (which is the same as a backfill). If your K-field is dependent upon other data sources, such as Lookup table, it does not recalculate because the Lookup table is updated. K-fields do not auto-update based on updates to their dependencies. Additionally, Available K-fields:
- Can be referred to universally in the application, including Filters.
- Experience Cloud updates all records immediately upon saving the K-field, that is, there is no need to manually backfill. Syntax change takes effect immediately
- Syntax commonly refers to fields with enumerated Alternative sets.
- Available K-fields are filled in from the Slug data set. All the fields used inside the K-field syntax need to be available in Slug, otherwise an error occurs.
- Cannot be used for a multi-valued K-field.
Backfill required — Calculate this K-field for new records as they enter Experience Cloud. Existing survey records do not have a value for this field until either the individual record is updated (any Feedback or Event field values change) or a backfill is performed. Use Backfill required if the calculation involves a text field (such as checking the presence of the word action in a comment), since text fields are not stored in Slug. Also use Backfill required when e_status is used in the K-field definition, since the field does not behave consistently until a full backfill has been run. Otherwise, use the a_status_enum field instead of e_status.
Additionally, Backfill required K-fields:
- Must be used if the K-field references a text field (such as is comment present with a Yes/No flag).
- Changes to the calculation do not take place automatically for existing surveys: you must manually backfill to update existing records.
- If a K-field is Backfill required and references other K-fields, those K-fields must also be Backfill required.
- May be used for a Multi-valued K-field. Any other field that references the Multi-valued K-field that is Backfill required must also be Backfill required.
Export only — Does not add this K-field to Slug. Common uses include rule conditions (such a Alert rules, Sampling filters, Case forms), record-level display purposes (Responses filter and Form), email templates, or if the K-field is multi-valued. As a best practice, use this for any K-field you do not need for filtering or aggregate reporting. Additionally, Export only K-fields:
- Can be used for Alert triggers.
- Has database access, such as using S3 (s3Key) to retrieve info from a Unit table.
- Using them for reports or filters results in either the question not appearing or an error message.
- May be used for a Multi-valued K-field.

Important: A K-field referencing a text or a Multi-valued field should be either Export only or Backfill required.

Support high cardinality auto-indexed...

Restriction: This feature is inactive by default. Ask your Medallia expert to file a Feature activation request with Medallia Support.

Important: Enabling this property requires engineering approval.

Allows the number of values in auto-indexed text fields and lookup tables to exceed the system limit of 600,000 to a maximum of 2,000,000. Ranking reporting is limited to a subset of the field's values defined by report filters. If the cardinality in any single report is too high, an error message noting the limit is displayed instructing the user to add filters in order to show data.

Alternative Set

The output of the calculation needs to conform to the Alternative Set selected here. For example, if Integer is selected, an output of 93.75 triggers this error: 93.75 invalid for int [0, 2147483647]. When you get this message, it means the Alternative set is expecting an integer output between 0 and 2147483647.

If you created a K-field and values are populated, and then later change the Alternative set, this does not trigger a recalculation and flags the K-field with an exclamation mark in parentheses on the screen.

Alternative Set ID

Automatically populated once an Alternative set is selected.

Calculation

JavaScript functions calculation that returns a result matching the Alternative Set. For example, if the Alternative set is Text, the calculation must return a text string. For more information, see:

Click Edit JavaScript to use the JavaScript editor for editing and testing the script, and accessing to a library of common functions:

Edit in JavaScript button opens the JavaScript Editor

To access the library of common scripts, click K-fields Library of the JavaScript editor. For more information, see K-field library.

When typing a script in the editor, press Control+Space to see a list of available functions and their descriptions. Type the first few characters first to see the function names that begin with the same text.

Example showing prompt: user entered "is" and three possible functions are listed with their descriptions, including isFinite(), isMemberOfUnitGoup(), and isUnitMemberOfUnitGroup()

Important: Medallia Experience Cloud uses a JavaScript processing engine called Mozilla Rhino — also known as the Rhino Engine — to provide flexibility for scripting. Access to the Rhino Engine is restricted by a ClassShutter mechanism, which implements arbitrary logic to determine whether Rhino can access the class. When access is denied, Experience Cloud shows an error message. To access a class that is not currently allowed, contact your Experience Cloud expert. For more information, see JavaScript allow-listing.

Client Identifier

Used for Survey Eexports if a client-specific label is needed.

Export label

Name to use for the field name (column heading) in the exported file when exporting this field. When this field is empty, Keyname is used instead.

This label may only contain alphanumeric characters and underscores.

Personally Identifying Data

Indicates the field contains personally identifying data on customers. The data in this field may be deleted or purged per the company's data retention policy, or if the field's record is subject to a GDPR or equivalent deletion request. For more information, see

TranslationExplanation

TranslationExplanation appends the prepended with k_. This creates a unique identifier that allows the K-field to be featured in other parts of Experience Cloud such as in a Dashboard module or report.

K-field functions

These are some of the JavaScript functions available for K-field calculations:

Tip: To see the list in the JavaScript editor, press Control+Space.


Function	What it does
`avg(int...)`	Average of the given integers.
`sum(int...)`	Sum of the given integers.
`coalesce(object...)`	First non-null argument.
`intFromPossibleEnum(object)`	Ordinal of enum or number.
`between(int v, int min, int max)`	Returns `true` if `v` is in the range `[min, max]`.
daysDifferenceByMidnights(date, date)	Previously known as date_diff. The number of days between two dates, counting midnight as a new day.
`daysDifferenceBy24Hours(date, date)`	The number of days between two dates, counting 24 hours as one days (rounded down).
`hoursDifference(date, date)`	The number of hours between two dates.
`millisDifference(date, date)`	Previously known as `msecsBetween`. The number of milliseconds between two dates.
`day_of_week(date, date)`	Checks which days of the week are between the two dates. For example, weekday only returns 1; weekend only returns 2; both returns 3).
`formatDate(date, pattern)`	Returns the date formatted according to the given DateFormat pattern. For example, pattern `yyyy/MM/dd HH:mm:ss.SSS` could be formatted as 2006/11/15 14:50:12.222.
`msecsBetween(date, date)`	Returns the number of milliseconds between two dates.
`formatMsecs(int)`	Returns a human readable string for a number of milliseconds.
`text(field)`	Returns text value of field.
`name(field)`	Returns name of an Alternative Set.
`date(field)`	Returns the date and time of field.
`now()`	Returns the date and time of current date and time.
`trim(string)`	Returns string with leading and trailing whitespace removed.
`seqnum(field)`	Returns the sequence number of the Alternative Set. from the field.
`unit`	Returns the unit with the given identifier.
`isUnitMemberOfUnitGroup(unit, unitGroupIdentifier)`	Returns true if the unit is a member of the unit group with the given identifier. For example, `isMemberOfUnitGroup(e_unitid, 'Wyoming')` returns `true` when the unit is a member of Wyoming. Restriction: Use this function only for Exports and select ExcludeFromSlug property.
`getUnitDatafield(Unit unit, String unitDataFieldKey)`	Returns the value of the data field for the given unit. Note that the `unitDataFieldKey` should not contain the `u_` prefix.
`getUnitGroupDatafield (unit, nodeName, maxDescendantLevel, unitGroupDatafieldKey)`	Returns the value of the given Unit Group data field by descending through the hierarchy of Unit Groups starting at `nodeName` up to `maxDescendantLevel` or until there are no more children. Note that the `unitGroupDatafieldKey` should not contain the `ug_` prefix. For example, this code snippet returns the current regional vice president unit group to which the unit belongs: `return getUnitGroupDatafield(e_unitid, 'regional_vice_president', 1, 'identifier');` Warning: When a Unit is member of more than one parent in the same parent Unit group, the K-field throws an error and returns blank for the record tied to that unit.
`lookup(tableName, key).columnName`	Returns the value of the data in the specified lookup table based on the lookup key. See examples below.
`url(string)`	Changes a string's type to URL. Note: K-fields that use the Content Kind Hyperlink require to wrap a String value in this function to pass its validation.
`__isClientSandbox()`	Returns true if the environment is a client sandbox. Restriction: To use this function, set SlugAvailability to Export only and use it only with fields that are Export only.
`__isProduction`	Returns `true` if the environment is production. Restriction: To use this function, set SlugAvailability to Export only and use it only with fields that are Export only.
`__isQA`	Returns `true` if the environment is QA. Restriction: To use this function, set SlugAvailability to Export only and use it only with fields that are Export only.
`amazonS3(string)`	Returns a URL to Amazon S3 for the given key. May be used on Responses Form to link to external resources. For example, `amazonS3('abcdefg')` returns `https://bucket.s3.amazonaws.com/abcdefg`. Restriction: To use this function, set SlugAvailability to Export only and use it only with fields that are Export only.

K-field library

Experience Cloud provides several built-in JavaScript functions functions in the K-field Library, such as the NPS function that returns the appropriate NPS segment based on the LTR score range.

To access the library, click K-fields Library in JavaScript editor.

Tips and best practices

Slug Availability selection should be based on where the K-field is used and how it should recalculate.
The basic step to check for K-fields is to ensure the data quality in reports. For example, the value of the output for K-field used should be closest to the value of the output from the Export generated.
Use the JavaScript editor to thoroughly test your K-field with different survey IDs. The editor displays intermediate values in your K-field calculation as well as the final output value. Test all cases.
Never reference the current date/time using now() or new Date(); instead, use a static field such as Creation date (e_creationdate).
K-fields that use the Hyperlink Content Kind require to wrap a string value in the url() function, as a String is not an accepted value.
By default, K-fields get text values from other fields in English language. However, for report Exports (Responses report, Invitations report) and record-level uses where the field is calculated as Available, Experience Cloud uses the user's language to determine the translation of the inputs to the K-field, which impacts its logic. For example, the Alert type field (a_alert_type field) is translated into the user's language different than English, and that text value (if called in the K-field) is translated as well.

For more information, see:

K-field dependencies

To understand when a record's K-field value is updated, especially when it has dependencies on other K-fields, consider these Slug principles:

Available K-fields means that everything that is needed to calculate it exists in Slug.

Restriction: Available Date K-fields do not behave consistently until a full Backfill has been run.
K-fields in Slug are updated when their definition changes, when the underlying survey is updated or created, during a Backfill, and cache rebuilds.

For example, consider three K-fields — A, B, and C — all of which are Available in Slug, where C derives from A and B. Changing A, such that it returns a different value for all records, does not automatically recalculate C across the Slug data set. Instead, you have to re-save C to trigger the recalculations.

Important: Updating a record's K-field is not a record-update because the underlying fields have changed.

A=f()
B=g()
C=A+B

For example, changing A's definition to A=f()+2 causes A to be updated in Slug. However, the underlying record does not get updated, C's definition does not change, and there is no Backfill or cache rebuild, so C is not updated in Slug.

Important: Updating a Lookup table or a Unit data field referenced by a K-field does not automatically cause an update because the value is not in the record.