Sync Custom Fields to Domain

As a service provider, you sometimes need extra information to resolve certain type of tickets. For such tickets, you can configure extra fields according to the requirements of your organization. Such fields are known as custom fields in ServiceAide Cloud Service Management (CSM).

You can add the custom fields to the data set domains in the application. You can then use such fields while creating Ad Hoc Views and reports. To add the custom fields to a domain, synchronize the domain with the custom fields data.

The procedure to sync custom fields with the Shared domain is different from the procedure for the Cloud SM domain.

Prerequisite

• Verify that the custom fields are created. For more information, see Create and Manage Custom Field Templates.
• Verify that you have the Domain designer permissions.

Follow these steps:

1. Log in to CSM and navigate to REPORTS, SERVICE DESK, Advanced Reporting.

   When adding custom fields, there are chances of domain getting corrupted. Hence it is important to take the backup of existing domain before new changes are made. Take a backup of domain files to roll back to the existing settings in case the files get corrupted. For more information, see Backup Domain Files and Restore Domain Files.

   If the domain files are not saved, the restoration is set to the default domain. The reports, ad hoc views, and dashboards that are created are lost.

   Verify that the custom field name does not contain accented characters. For example, situação_id162 is a custom field with accented characters.

2. To make the custom field available in advanced reporting, click Actions, Sync Custom Fields.
   A list of available custom fields are displayed in a new tab. If the custom fields are already added to the domain, the list displays the fields as checked.

   Note: For better performance, synchronize the custom fields that are necessary in the reports. The maximum limit to synchronize the configurable custom fields is 50.
   The custom attribute with the name Join is not supported in Advanced Reporting. However, the name Join is supported if it is prefixed or suffixed. For example, a custom attribute name attributJoin or joinAttribute is supported.

3. Select the custom fields that you want to add and clear the fields that you want to remove. Click Sync.
   A confirmation message is displayed and the custom fields are added or removed from the domain.

4. If you are using the Cloud SM domain, perform step 5. If you are using the Shared domain, perform steps 6 – 12.

5. Verify that the custom fields are added to the domain:

   1. Click the Home tab and then click Actions, Create Ad Hoc View.

   2. Select the Cloud SM domain and click Choose Data.

   3. From the Source panel, go to the data set such as Tickets or Configuration Items. Verify that the custom fields are added to the Custom Attributes folder under their respective data set.

6. If you are using the Shared domain, click Home tab and then click Actions, Edit Domain. The Edit Domain page opens in a new window.
7. From the Domain Design, click Edit with Domain Designer. The Domain Designer window opens.

8. In the Calculated Fields tab, convert the custom field with non-string data types to their respective data types.

   The custom fields with data types such as Integer, Double, and Boolean are stored as string data type. Convert the data type to the original data type, to display them properly in the report.

   1. The created custom field is available in the _PIVOT tables of the respective type. For example, if you create a custom field of the type service request, the field is available in the following table:
      dbo_VAPP_SERVICE_REQUEST_ATTRIBUTES_PIVOT table.
      

   2. Double-click the custom field for which you want to change the data type.

   3. Enter the field name, data type, and expression for the conversion. The following list of expressions are used to convert the data types:

      Data Type	Expression	Description
      Integer	str2int(custom field)	To convert to an integer. For example, to convert the Ticket_Id field in the dbo_VAPP_SERVICE_REQUEST_ATTRIBUTES_PIVOT table, enter the following values: Field Name: Ticket_Id_trasnform Type: Integer Expression: str2int(dbo_VAPP_SERVICE_REQUEST_ATTRIBUTES_PIVOT.Ticket_Id)
      Double	str2double(custom field)	To convert to a double. For example, to convert TotalCost field in the dbo_VAPP_SERVICE_REQUEST_ATTRIBUTES_PIVOT table, enter the following values: Field Name: TotalCost_transform Type: Double Expression: str2int(dbo_VAPP_SERVICE_REQUEST_ATTRIBUTES_PIVOT.TotalCost)
      Date	EPOCH_TO_UTC_DATETIME(str2int(custom field))	To convert to date format. For example, to convert the start_date field in the dbo_VAPP_SERVICE_REQUEST_ATTRIBUTES_PIVOT table, enter the following values: Field Name: start_date_transform Type: Timestamp Expression: EPOCH_TO_UTC_DATETIME str2int(dbo_VAPP_SERVICE_REQUEST_ATTRIBUTES_PIVOT.start_date))
      String - concatenation	concat(custom field 1, ’,’,custom field 2)	To join two strings into one. For example, to convert the contact_person field in the dbo_VAPP_ITEM table, enter the following values: Field Name: contact_person Type: String Expression: concat(dbo_VAPP_ITEM.person_last_name,',', dbo_VAPP_ITEM.person_first_name)

9. In the Display tab, add the custom fields from Resource panel to Sets and Items panel and click OK. 

   Select the required custom fields and its attributes that are useful in building or filtering reports. You can modify the display properties, such as label, description of tables, and sets and items for each selected field. Perform the following tasks in the Display tab:
   

   In the Resource panel, locate the custom field and attributes that you want to add from a JoinTree. All the custom fields and attributes are available in the Pivot tables. The attributes are listed according to the Related to Form field of the template to which it is added.
   For example, you have created an attribute ITEM_ID and add to the template that is related to Change Request. You find the ITEM_ID attribute in the dbo_VAPP_CHANGE_ATTRIBUTES_PIVOT table in the JoinTree.

   To move the custom attribute from Resources panel:
   
   • Use the Add to Sets icon, to add under a set in Sets and Items panel.
   • Use the Add to Selected Set icon, as a new set to Sets and Items panel
   To remove an attribute in a set, select the attribute from Sets and Items, and click Delete Item.
   Note: verify that the field ID is unique for each custom field.
   

10. (Optional) To enable the translation of custom fields into a required language:

    1. Select the custom attribute from the Sets and Items panel, and in the Properties panel, click Edit.

    2. Enter Label Key and Description Key, and click Save.

       • The format of Label Key is Data Set_Ticket Type_Custom Field_Label

       • The format of Description Key is Data Set_Ticket Type_Custom Field_Description 
         

    3. From the Edit Domain page, download the required locale file from the Locale Bundles. For example, the locale file for French is suffixed with _fr_FR and Brazilian is suffixed with _pr_BR.

    4. Open the locale file in an editor and add the attribute information.
       For example, for Ticket ID attribute added with Label Key as Ticket_ID and Description Key as Ticket_ID_Desc, in the French locale file:
       Ticket_ID=Identification de billets 
       Ticket_ID_Desc=Ticket numéro d'identification

    5. Save and exit the file.

    6. From the Edit Domain page, click Change to the corresponding locale file. Browse the locale file and click Select. The locale file is updated with the custom attribute information.

11. Click OK. The edit domain page opens.

12. Click Submit. The custom fields are added to the domains. Now you can use these custom fields to create Ad Hoc views and reports.

    If the Advanced Reporting is not working properly after updating the domain, restore the domain to the recently saved files. For more information, see Restore Domain Files.

Custom Field Support for Asset

For each of the OOTB asset templates, the application has ten custom attributes(Attribute 1-Attribute 10) exposed. These custom attributes can be mapped to the custom attribute that you add. For example, you add a custom attribute name- Cubicle Number to the Hardware Asset Template. The Attribute 1 in the hardware asset set in the domain maps to this newly added attribute. You can change the labels of the attributes as you would like them to appear in the report.

Backup Domain Files

Take a backup of the domain files before adding the custom fields to domains. The backup procedure includes saving the security and domain design files to local computer. If the domain is corrupted, use these files to restore the Advanced Reporting settings to the recently saved files.

Follow these steps:

1. Log in to CSM and navigate to REPORTS, Advanced Reporting, Actions, Edit Domain.
2. Security file: In Edit Domain page locate custom_cloud_sm_security.xml in the top-right corner. Click custom_cloud_security.xml and save it to the local computer in the location of your choice.
3. Domain design file: Click Edit with Domain Designer, Export Design and save the schema.xml file to the local computer in the location of your choice.

Restore Domain Files

If Advanced Reporting feature is not working properly after updating the domain, use the saved security and domain design files to restore functionality. The restoration is done to recently saved files.  

Follow these steps:

1. Navigate to REPORTS, SERVICE DESK, Advanced Reporting, Actions, and click Edit Domain.
2. Security file:
   1. Locate custom_cloud_sm_security.xml in the Optional Information section. Click Remove to remove the existing security file from the application.
   2. Click Add Security File in the Optional Information section. Upload the security file from the location where you saved domain files backup and click Select.
      The security file is restored.
3. Domain design file:
   1. Select Domain option and click Browse.
   2. Upload the domain design file from the location where you saved backup and a confirmation message opens. Click OK.
      The domain is restored. 
   3. To validate the restoration, click Edit with Domain Designer and click Check Design.