JSON Screen Configurations

Source: This article refers to JSON Screen Configurations


Attention: Supported screens can now be configured and customized using the Screen Configuration tool located in the Admin module. Screens not supported can still be configured and customized using the steps outlined in the following document.

1 Introduction

Note: This documentation is intended for consultants and partners only.

With screen configurations, you can customize the following field properties:

  • Hiding or displaying fields
  • Making fields read-only or editable
  • Making fields mandatory (required) or optional
  • Define the default value for fields when creating new objects
  • Renaming labels incl. custom translation

This documentation describes how to customize screens in the Coresystems Field Service Management (FSM) Solution.


1.1 What is the Customization Feature?

Thanks to the Customization feature in the Coresystems FSM solution you will be able to do the following:

  • Configure screens to fulfill customer-specific requirements. This includes hiding, displaying, moving or grouping fields displayed on a screen and making fields mandatory, optional, read-only or editable.
  • Adjust labels and translations for customer-specific wording. The adjusted translations will be used in all FSM apps and reports.
  • Define workflows for customer-specific service processes.

1.2 Which Screens are Configurable?

Screen Code Configuration UI iOS Mobile Windows Mobile Android Mobile Web
Activity X (without web) X X X CSActivitySidebar
Business Partner - X - X -
Effort - X X X -
Expense - X X X -
Items & Stock - X - X -
Material X X X X -
Mileage X X X X -
SalesOpportunity - X X X -
SalesOrder - - - - -
SalesQuotation - - - - -
ServiceCall - X X X CSServiceCallDetail
ServiceCheckout - X - - -
ServiceContract - X - X -

On these screens, you can customize the following field properties:

  • Change a field description by renaming a label or use a custom translation
  • Remove a field from the screen
  • Change the screen layout by changing the position of the fields
  • Set a field to be mandatory or optional
  • Set a field to be read-only or editable
  • Adjust a default value

1.3 Requirements

To configure the screens, you need a basic technical understanding of JSON files.

The sample JSON structure and some tips on how to adjust the file is provided in this documentation. The adjusted JSON structure can be defined in the settings module of the Service Cloud. To perform customizations, you need permission for creating and editing the Screen Configuration.



1.4 Further Consideration

In order to improve the feature to keep the app logic for fields that are not configured we had to make bigger changes in the structure of the JSON. This also means that the previous structure is no longer supported by the iOS App. When updating the app it is therefore required to update the Screen Configuration.


2 Technical Details

2.1 JSON Structure

In the “preview” release there is no user interface to adjust the screen configuration. Therefore some technical understanding is required to adjust the screen configuration JSON (short for JavaScript Object Notation), which is a standard way to store information in an organized, easy-to-access manner.

The screen configuration JSON describes the fields on a screen and their layout. It applies to both view and add/edit screens.

There are two main components that comprise the JSON screen configuration:

Layout The “layout” section is the first part of a screen configuration JSON that defines the display, order and grouping of fields on the screen.
Fields Configuration The “fieldsConfiguration” section is the second part of the screen configuration JSON that defines the different properties per field. Here you can define the naming or translation key of a label, choose for each field if it should be visible, editable, required or not or set default values and value validation per field.

2.2 Supported Field Properites

Each field may contain a definition of customizable properties.

Example: Define that the origin of a Service Call is required:

{ "name": "serviceCall.origin", "required": "true" }

See below the technical details for supported properties.


2.2.1 Visible

The “visible” property defines if a field should be visible on the screen in create, edit or view mode or not.

Attributes

  • Valid Values: “true” or “false”

Notes

  • If the “visible” property is set to “false”, the field is never displayed, regardless of the screen configuration layout or any additional application logic.
  • If the “visible” property is set to “true”, the field is displayed only if
    • The field is defined in the screen configuration layout AND
    • There is no logic in the application that would actively hide the field.

2.3.2 Editable

The “editable” property defines if the field should be editable in edit mode of a screen or not.

  • Valid Values: “true” or “false”

Notes

  • The “editable” property has no influence in view mode, i.e. in view mode clickable/selectable fields are always selectable for example when navigating to a related object.

2.3.3 Required

The “required” property defines if the field is required in edit or create mode of a screen or not.

  • Valid Values: “true” or “false”

Notes

  • If the “required” property is set to “true” then the field is always required, regardless of any additional application logic
  • If the “required” property is set to “false” then the field is required only if there is no logic in the application that would actively set the field as required.

2.3.4 Default Value

The “defaultValue” defines the value that be used to prefill the corresponding field when creating a new object.

Valid Values

  • Any value of type string, number, Boolean, date (format ‘2012-04-23T18:25:43’)

2.3.5 Expressions

In addition to the static properties above, it is also possible to use JavaScript expressions that are evaluated in order to decide if a field is required, visible, editable and what is its initial value.

These expressions may contain references to any other fields in the screen that are of type string, number, date, bool or udf. A reference to relationship fields is currently not supported.

The following expression properties exist:

Expression Type Description
“visibleExpression” Function that must return a boolean value
“requiredExpression” Function that must return a boolean value
“editableExpression” Function that must return a boolean value
“defaultValueExpression” Function that must return a boolean, string, number or date
“validationExpression” Function that must return a boolean value indicating if the entered value is valid or not
“validationErrorMessage” Defines the text to be displayed to the user when the field is not valid according to the above condition

Condition

  • If for a certain property both the expression and static are defined
    • The static property is overwritten by the expression property in case the expression is valid.

Example

  • If the property “visibleExpression” is defined and returns “false” in the expression for a certain screen the field is not displayed on the screen even if the static property “visible” is set to “true”.
  • if the expression evaluation is not valid (i.e. the expression contains errors) the corresponding static property is use as fallback

Example

  • If the property “visibleExpression” is defined and returns an exception or error in the expression for a certain screen the field is displayed depending on what was defined for the static property “visible”

Limitations

  • Expressions of type “count(relation)” are not supported due to performance risks

2.3.6 Display Properties

The property “displayProperties” is relevant only when a field is links to related objects. Here you can define which properties of the related object should be displayed on the screen.

The “property” represents the name of a field on the related object’s DTO.

Example

If the related object is a BusinessPartnerDTO then “property” could be “code” or “name”. Refer to the DTO Table in the Appendix for more information about relations between objects and the available fields.

Notes

  • It is not supported to display relationships of two levels. In the example above this means it is not supported to use “defaultContact.name”, or “defaultContact.address.name”. In other words it means the “property” value must not contain dots (“.”) to link to another object.
  • For related objects the “displayProperties” field is mandatory. If the “displayProperties” is not defined for a related object, nothing will be displayed on the screen.

2.2.7 Translation Key

The property “translationKey” allows defining custom translations for field labels. If the field configuration has a “translationKey” and a matching translation for this key and the current application language is defined for the company, the translated value is displayed as field label.


2.3 Standard Behavior vs. Static Customization vs. Customization with Expressions

The current applications have some business logic implemented that we did not want to lose when using a screen configuration to simply hide a certain field. Therefore we adjusted the structure of the JSON in the release 5.25 to keep the app logic in case nothing else is defined.

Important Rules

  • In case no property is defined the standard app logic is used
  • In case a static property e.g. “visible” is defined it overwrites the standard app logic
  • If case both the static property, e.g. “visible” and the conditional property, e.g. “visibleExpression” is defined the conditional property overwrites the static property.
  • In case there is an error or exception in the conditional property the static property is used in case it is defined. If no static property is defined the standard logic is used.

2.3.1 Maintain Standard App Logic

The Business Partner is displayed on the Service Call Screen and that is OK for the customer. In that case there should be no “visible” property be defined for the Business Partner.

{ "name": "serviceCall.businessPartner" }

2.3.2 Change Standard Logic with Static Property

The Origin is displayed on the Service Call Screen and the customer does not use this field at all and wants to hide it always. In that case there should be a “visible” property defined for the Origin field.

{ "name": "serviceCall.origin", "visible": "false" }

2.3.3 Change Standard Logic with Conditional Property

The Origin is displayed on the Service Call Screen and the customer uses this field only for certain service call types and wants to hide it for others. In that case there should be a “visibleExpression” property defined for the Origin field.

{ "name": "serviceCall.origin", "visible": "false", "visibleExpression": "${serviceCall.type} = -1" }

2.4 How to Adjust Field Properties

Field Description
Description Required. The text displayed in the label. This can be changed to suit your preferences and needs.
Default Value If applicable, the default value to be displayed.
Visibility Choices include: Default, Visible, Hidden.
Editability Choices include: Default, editable, read-only.
Required Choices include: Default, Required, Optional.

Each field contains a definition of customizable properties. To change a property, you must change the value from to “true” to “false” or the other way around. To rename the label of a field, you must adjust the title of the displayProperties.

Example for the field Origin in the Service Call Screen:

"servicecall.origin": { "default": null, "visible": "true", "editable": "true", "property": "origin", "required": "false", "valueValidation": null, "displayProperties": [ { "title": "Origin", "property": "originName" } ] }

2.5 How to Find the Correct Unique Identifer

The unique identifier of a field is the field name.

  • For standard fields, the field name is a combination of object name and field name, e.g. “serviceCall.code”. Refer to the DTO table in the appendix below for more information on data objects and field names.
  • For User-Defined Fields (UDF), the field name is defined as “udfMeta.X” where “udfMeta.” is a prefix and “X” is the actual name of the UDF (UdfMeta.Name), e.g. “udfMeta. U_COR_CLOUD_ScLead” (See also chapter 2.7 for details how to configure custom fields)
  • For fields of related objects, the field name is defined as “relation.X” where “relation.” is a prefix and “X” is the actual name of the field, e.g. “relation.signature”, “relation.defaultContact”, “relation.allContacts”

2.6 How to Configure Custom Fields

A custom field is a field that does not exist in the standard Coresystems data table object (DTO). Each company may have different custom fields. Therefore, make sure that the field exists in the company for which you configure the screen.

To adjust the customization for custom fields, you must use the “name” of the custom field.

For companies that are connected to a SAP Business One ERP the name of the UDF on the Coresystems cloud is the same as the name that is displayed in the settings of the UDF in SAP Business One.

Example:

In the SAP Business One database, the custom field for Service Call Leader has the field name “U_COR_CLOUD_ScLead”. However, the actual name in SAP Business One and the Coresystems cloud is “COR_CLOUD_ScLead” (without the “U_”), and this is also the field name to use in the configuration.

The entry in the JSON for the screen configuration will be:

"udfMeta.COR_CLOUD_ScLead": { "entity": "udfMeta", "property": "COR_CLOUD_ScLead", "title": "Leader", "visible”": "false", "editable": "true", "required": "false", "valueValidation": null, "displayProperties": [ { "title": "Leader", "property": "COR_CLOUD_ScLead" } ] }

Note

It is possible to define if a User-Defined Fields is mandatory on database level in the property “UdfMeta.Mandatory”. This is important in case the User-Defined Field is mandatory in the ERP System that created the User-Defined Field.

The following rules apply in this special case

  • If UdfMeta.Mandatory is set to “true”, then the UDF field is always required, regardless of any settings in the screen configuration
  • If UdfMeta.Mandatory is set to “false”, then the UDF field is required only if the “required” property is set to “true” in the screen configuration

3 Implementation

The user who configures the screens needs the “Screen Configuration” permission and a subscription for the company.

3.1 Creating a New Configuration

To create a new screen coniguration, complete the following steps:

  1. Login to my.coresuite.com with a user that has the required permissions.
  2. Go to Settings > General > Customization.
  3. Create a new Configuration.
  4. Enter a code for the configuration. We recommend you enter a readable code, e.g ServiceCallForTechnicians. This code will also be used as the name of the configuration in the overview in my.coresuite.com.
  5. Select an object type (refer to DTO table above for more information).
  6. The “Embedded” setting is not relevant at the moment.
  7. Enter “1” as schema version.
  8. Enter the configuration. (See chapter 2 on the technical details for the screen configuration.)


  1. Save the new screen configuration.

3.1.1 Testing the Configuration

To test the screen configuration, complete the following steps:

  1. Login to the app with a user that has permissions to create, edit and view the relevant object. (See chapter 1.2 for an overview over which client apps are supported.)
  2. Synchronize data.
  3. Create a new object and verify that the changes have been applied.

Appendix

DTO Table

All data table objects (DTOs) are documented in the following table:


Default Service Call Screen Configuration

THe following is a JSON representation of the default Service Call screen configurations:


Default Expense Screen Configuration

The following is a JSON representation of the default Expense screen configuration:

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.