Functions for Case Management Studio

Overview

In Case Management Studio, forms are the primary way that your end users interact with their cases. Forms allow end users to create and edit cases, and help users provide your case workers and managers with the information that they need to complete a case or address an issue.

When you create a form in Studio, we automatically generate an interface for that form in Designer. Being able to configure an interface in Designer allows you to make more extensive configurations beyond those possible in Studio

In Designer, you can edit the generated interfaces for your forms practically the same way you would for any other interface. The only difference is that there are special functions used in case management interfaces. These functions are specific to interfaces generated by Studio and cannot be used in other interfaces or applications that aren't used in your case management app.

This page is intended for low-code developers and provides an overview of the Studio specific functions and their purposes.

Case Management Studio specific functions

Studio uses drag and drop components that are similar to typical interface components that you would find in Designer, but can be fully configured without using any code.

The interfaces generated by Studio reference the no-code components in their expression using special functions that can only be used in interfaces for your case management apps. Just like any Appian function or interface component, you can configure these special functions by editing their parameters and values.

Studio specific functions that can be used in interfaces

Here is a list of the functions that can be used in interfaces in your case management apps or that are generated by Studio, along with a description and a list of their parameters.

Function	Description	Parameters
a!studio_booleanCheckboxField()	Creates a checkbox field with one option that handles a boolean value.	label, instructions, required, disabled, choiceLabel, value, validations, saveInto, validationGroup, requiredMessage, align, labelPosition, helpTooltip, accessibilityText, showWhen, choiceStyle
a!studio_descriptionField()	A description component that returns rich text display field.	value, showWhen
a!studio_dropdownField()	Displays a list of choices from a record type for the user to select one item and saves a value based on the selected choice. Automatically applies an isActive filter if a field with that name is present on the record type, and will sort by a sortOrder field if one is present on the record type.	label, instructions, required, readOnly, disabled, value, validations, saveInto, validationGroup, requiredMessage, align, placeholder, helpTooltip, accessibilityText, characterLimit, showWhen
a!studio_emailAddressField()	Creates a simple field for inputting an email address. Automatically validates that the email address has an appropriate format.	label, instructions, required, readOnly, disabled, value, validations, saveInto, validationGroup, requiredMessage, align, placeholder, helpTooltip, accessibilityText, characterLimit, showWhen
a!studio_image()	Returns a stock image as a Web Image.	seed, caption, showWhen
a!studio_readOnlyDisplayField()	Displays read-only data in a standard manner. The underlying display is dynamic based on the type of the input value. This function is only used in case summary views.	label, value, showWhen
a!studio_safeLinkField()	Creates a safe link field that opens in a new tab when clicked.	label, webAddress, instructions, align, showWhen
a!studio_titleField()	Displays a standalone section title using an h3 heading level.	label, showWhen, marginBelow, accessibilityText, labelIcon, iconAltText, labelSize, labelHeadingTag, labelColor, marginAbove
a!studio_validateDateIsAfterRelative()	Returns a message if the date given is not an appropriate number of days after the current day.	date, offsetDays, includesTargetDate, validateWhen
a!studio_validateDateIsAfterTarget()	Returns a message if the date given is not an appropriate number of days after the target date.	date, targetDate, includesTargetDate, validateWhen
a!studio_validateDateIsBeforeRelative()	Returns a message if the date given is not an appropriate number of days before the current day.	date, offsetDays, includesTargetDate, validateWhen
a!studio_validateDateIsBeforeTarget()	Returns a message if the date given is not an appropriate number of days before the target date.	date, targetDate, includesTargetDate, validateWhen
a!studio_validateDatetimeIsAfterRelative()	Returns a message if the date given is not an appropriate number of days after the current day.	datetime, offsetDays, validateWhen
a!studio_validateDatetimeIsAfterTarget()	Returns a message if the date and time given is not an appropriate number of days after the target date and time.	datetime, targetDatetime, validateWhen
a!studio_validateDatetimeIsBeforeRelative()	Returns a message if the date and time given is not an appropriate number of days before the current date and time.	datetime, offsetDays, validateWhen
a!studio_validateDatetimeIsBeforeTarget()	Returns a message if the date and time given is not an appropriate number of days before the target date and time.	datetime, targetDatetime, validateWhen
a!studio_validateEmailAddressAllowedDomains()	Given an email address and a list of email domains, validates whether the email address domain is in the list.	emailAddress, allowedDomains, validateWhen
a!studio_validateNumberBetweenLimits()	Returns a message if the given number value is not between provided number limit values.	number, upperLimit, lowerLimit, includeLimitValues, validateWhen
a!studio_validateNumberGreaterThanLowerLimit()	Returns a message if the given number value is not greater than provided number limit.	number, limit, includeLimitValue, validateWhen
a!studio_validateNumberLessThanUpperLimit()	Returns a message if the given number value is not less than provided number limit.	number, limit, includeLimitValue, validateWhen
a!studio_validateTextLengthExact()	Returns a message if the entered text value does not match the length specified.	text, limit, useBytes, validateWhen
a!studio_validateTextLengthMax()	Returns a message if the entered text value is longer than the length specified.	text, limit, useBytes, validateWhen
a!studio_validateTextLengthMin()	Returns a message if the entered text value is shorter than the length specified.	text, limit, useBytes, validateWhen
a!studio_validateTextMustContain()	Returns a message if the given text value does not contain the given text.	text, mustContain, caseSensitive, validateWhen
a!studio_validateTextMustNotContain()	Returns a message if the entered text value contains the text specified.	text, mustNotContain, caseSensitive, validateWhen
a!studio_wizardLayout()	Studio interface to display a list of pages in a wizard.	label, sections, formStyle, formIntent, hasLeadingPage, hasFollowingPage, onSubmit, onCancel, onBack
a!studio_wizardSection()	Displays a page that can be used within a!studio_wizardLayout.	label, contents, showWhen
a!studio_yesNoRadioButtonField()	Creates a radio button field with two options (yes and no) that handles a boolean value.	label, instructions, required, disabled, value, validations, saveInto, labelPosition, helpTooltip, accessibilityText, showWhen, choiceStyle, choiceLayout, validationGroup, requiredMessage, spacing

Studio specific functions that can't be used in interfaces

Some Studio specific functions can't be used in interfaces and are internally used to set other configurations for your case management apps. Here is a list of these functions, along with a description, a list of their parameters, and an explanation of what each function is used for.

Function	Description	Parameters	Purpose
a!studio_brandingPalette()	Returns a map of colors used in Appian Solutions.	None	Used in Studio to handle any color configurations.
a!studio_dataManager()	Studio interface to view and edit a record type definition.	recordTypeUuid, recordTypeUuidsToHide, application, referenceRecordTypePrefix, label	Used in Studio to handle data field design.
a!studio_displayBuilder()	Studio interface to build a display form.	interfaceUuid, label, usableRecordTypeUuids, application, errorLabel, errorMessage	Used in Studio to handle summary design.
a!studio_formBuilder()	Studio interface to build an intake form.	interfaceUuid, usableRecordTypeUuids, application, sectionStyle, interfaceUuidToCopy, errorLabel, errorMessage, onClose	Used in Studio to handle form design.
a!studio_getRuntimeData()	Executes a query for a studio-defined record type and returns the resulting data.	recordTypeUuid, identifierField, identifier	Used to pre-populate data in the Edit forms for case types.
a!studio_interfaceCreator()	Displays a button that creates an interface by specification.	buttonLabel, interfaceName, interfaceTemplate, selectorInterface, recordTypeUuid, identifierField, application, onCreate	Used in Studio to handle creating new interfaces for forms.
a!studio_recordFromJson()	Converts a JSON string into a record type instance.	json	Used by the Public Portal module as part of case creation.
a!studio_recordToJson()	Converts a record type instance into a JSON string.	data	Used by the Public Portal module as part of case creation.
a!studio_recordTypeCreator()	Displays a button that creates an record type by specification.	buttonLabel, recordTypeName, recordTypeDisplayName, parentRecordTypeUuid, application, onCreate	Used in Studio to handle creating new record types for case types or categories.
a!studio_safePreview()	Displays a preview with a fallback if the expression errors.	expression, errorLabel, errorMessage	Used in Studio to handle error cases.
a!studio_writeStudioRecords()	Smart service to write both studio and application records. The writes will happen sequentially via separate smart service calls, akin to multiple chained Write Records process model nodes.	studioRecord, applicationRecord, onSuccess, onError	Used to write data for a case type. Handles updating the case type, case category, and all cases record types.

Best practices

Follow these best practices for configuring forms to ensure that business users can continue to use all form building capabilities in Studio:

• The interface is a list of a!studio_wizardSection().
  • If you remove this function from your interface, you will only be able to preview the form in Studio and will be unable to edit it.
• Within a given section of the wizard, the contents parameter is a list and only contains components that are available in Studio.
• Only use a!localVariables() at the top level of the interface.

Interface configurations that don't follow the best practices can result in business users having less flexibility to edit forms in Studio. While you will still be able to preview these forms in Studio, you can only edit the parts of the form that follow the best practices.

Here are a few examples of interface configurations that will cause you to be unable to configure the associated components in Studio, though you can still rearrange them in the form.

• UI components that aren't available in Studio.
• Rules or component plug-ins that returns UI elements.
• Columns or other layouts in a section of a wizard.

Usage considerations

• When the user submits the form without interacting with Boolean and Yes/No fields, those fields save a value of false to the mapped data field.
• The Email Address field already includes a validation to check that the user's input is correctly formatted as an email address, so you don't need to add a custom validation to check the formatting.
• Dropdown fields are configured to handle inactive values when the corresponding record type for the choice list has a field called isActive.
  • This is useful when a choice list represents values that may change over time and one of the choices becomes obsolete.
  • When a user launches the Edit Additional Details action from the case summary view in Workspace and there's an isActive choice in a dropdown field, the user is prompted to choose one of the active choices before submitting the form.

Feedback