Business Object References

Business Object References are dedicated types that allow you to refer to Business Objects in Appway scripts in a safe manner. In contrast to the approach of referencing a Business Object using a simple String, Business Object References come with the guarantee that Appway's design-time dependency framework correctly tracks the Business Objects through their references.

See the list of supported Business Object types and an overview of the functions and Studio properties where Business Object References can be used.

Creating a Business Object Reference

A Business Object Reference is a reference to a Business Object of a given type and using it guarantees the Appway dependency framework works correctly. Appway provides the following reference types (as normal Data Classes):

  • Catalog:Reference
  • DataClass:Reference
  • Format:Reference
  • Label:Reference
  • Package:Reference
  • Process:Reference
  • Screen:Reference
  • Resource:Reference
  • Rule:Reference
  • RuleSet:Reference
  • Screen:Reference
  • DocumentCategory:Reference
Important! To be able to use these Data Classes, your Package needs to declare a dependency on the source Package. For each supported Business Object type, a dedicated Appway Platform Package is preinstalled and contains the according reference Data Class. For example, to use `Process:Reference`, declare a dependency on the Process Package. Dependencies are defined on the Properties tab of your Package.nnFor the Base Package, an implicit dependency on all Appway Platform Packages is declared by default.nnPlatform Packages are automatically installed when starting Appway, they are sealed (cannot be modified), and are not shown in the Package overview with other Packages.

To instantiate a Business Object Reference, use the dedicated function for the according Business Object Reference type. These dedicated functions use the form [BusinessObjectType]:NewReference(String), e.g. Process:NewReference. Note that these functions accept only String constants; String variables or expressions cannot be used.

Examples of Use

  • Creating a Screen reference and using it in a function:
    Copy
        Screen:Reference $screenRef  :=  Screen:NewReference("MyTemplate");
        SCREENURL($screenRef);
  • Creating a Process reference and using it in a function:
    Copy
        Process:Reference $myProcess := Process:NewReference("Demo:MyProcess");
        StartProcess($myProcess);
  • Creating an assigned variable on the Variables tab, e.g. for a Screen to be used in a Process: The Variables tab of a Process Business Object with the variable screenRef set

Then, you can use this variable to refer to the Screen to be used in a Screen Task: Using the screenRef variable to define a Screen Task

Finally, when calling the Process, you instantiate $screenRef with a Screen Reference using a standard variable assignment. This allows setting up a Solution to use different Screens in the Screen Task depending on the context, while ensuring dependencies are tracked correctly.

Notes:
  • Once a Business Object Reference has been instantiated, it cannot be modified.
  • You cannot assign a value directly to a Business Object Reference, you must always use the dedicated function for instantiation.
  • You cannot inherit from Business Object References.

Business Object Reference Support in Appway

Business Object References are supported for the following Business Object types:

  • Catalogs
  • Packages
  • Processes
  • Screens
  • Resources
  • Rules
  • Rule Sets
  • Data Classes
  • Document Categories

See the following subsections for details on the functions and Studio properties that support the use of Business Object References.

Important! The function and Studio properties listed below support Business Object References, but also continue to support Business Object IDs which are provided as `Strings`. This ensures that there is no migration effort and that running Processes will continue to run as before. nnValidation returns an INFO message when `Strings` are used in locations that support Business Object References.

Screen Components

The following Screen Components support Business Object References:

  • HTML Head Link
  • HTML Head Script
  • Image
  • Include
  • Link
  • Link Container
  • Process Include
  • Raw Code
  • Resource Include
  • Screen Include
  • Screen Link
  • Template
  • Workflow Image

Screen Actions

The following Screen Actions support Business Object References:

  • Display Process Action
  • Display Resource Action
  • Display Screen Action
  • Display Sub-Process Action

Process Components

The following Process Components support Business Object References:

  • Evaluate Rule Set Task
  • Evaluate Rule Task
  • Screen Task
  • Sub-Process

Appway Functions

The following functions support Business Object References:

  • CatalogueDelete
  • CatalogueUpdate
  • EVALUATERULE
  • EVALUATERULESET
  • GetSubWorkflowTokenId
  • LIST
  • ProcessElementId
  • ProcessStartURL
  • READTEXTRESOURCE
  • Record
  • RECORDS
  • RESOURCEURL
  • SCREENURL
  • StartProcess
  • StartSubProcess
  • WRITETEXTRESOURCE

Moreover, Script Functions in the following extensions support DataClass References:

  • Business Data Storage (All functions are described in the related documentation)
  • Data History (All functions are described in the related documentation)

Referencing Business Objects using Strings

Business Object References should always be preferred over Strings when referencing Business Objects. The following examples demonstrate how Appway's dependency check can break when defining a Business Object ID as a String. The StartProcess function is an example of a function that, before Appway 9, accepts only a Business Object ID provided as a String.

  • You can define the Business Object ID directly:
    Copy
        StartProcess("Demo:MyProcess")
    This function works at runtime, and the StartProcess function is built in a way that the design-time dependency check also functions correctly.
  • Alternatively, the usage of Strings allows you to create a variable of the type String and use the variable in the StartProcess function:
    Copy
        String $myProcess := "Demo:MyProcess";
        StartProcess($myProcess);
    Or you could use an expression, e.g. concatenating two Strings:
    Copy
        StartProcess("Demo:" & "Process");
    Both of these functions work at runtime and are valid regarding the use of Strings, but the design-time dependency breaks, i.e. the StartProcess function cannot track the dependency on Demo:Process. Broken dependencies mean many features in Appway will no longer work correctly, e.g.:
    • Refactoring IDs
    • Moving Business Objects between Packages
    • Selection of dependent Business Objects when exporting a Business Object

By using Business Object References, you can ensure the design-time dependency framework is not broken under any circumstances.