Use case: Manage field definitions in an organization

You can use the Unity Cloud Assets package to create, delete, and edit the field definitions of an organization.

Note

To create, delete, and edit the field definitions of an organization, you need the Asset Manager Admin role at the organization level.

Before you start

Before you start, do the following:

1. Set up a Unity scene in the Unity Editor with an Organization and Project browser. Read more about setting up a Unity scene.

2. Create assets in Unity Cloud any of the following ways:

   • Add assets using the Asset SDK.
   • Add single or multiple assets through the dashboard.

How do I...?

List and select the field definitions in an organization

To list the existing field definitions in an Organization, follow these steps:

1. Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
2. Add the following code to the end of the class:

public Dictionary<string, FieldDefinitionProperties> FieldDefinitionProperties { get; } = new();
public string CurrentFieldDefinitionKey { get; private set; }
public FieldDefinitionUpdate FieldDefinitionUpdate { get; private set; }

public async Task GetFieldDefinitionsAsync()
{
    var fieldKey = CurrentFieldDefinitionKey;
    CurrentFieldDefinitionKey = null;
    FieldDefinitionProperties.Clear();

    var asyncList = PlatformServices.AssetRepository.ListFieldDefinitionsAsync(CurrentOrganization.Id, Range.All, CancellationToken.None);
    await foreach (var fieldDefinition in asyncList)
    {
        var properties = await fieldDefinition.GetPropertiesAsync(CancellationToken.None);

        FieldDefinitionProperties.Add(fieldDefinition.Descriptor.FieldKey, properties);

        if (fieldDefinition.Descriptor.FieldKey == fieldKey)
        {
            SetCurrentFieldDefinition(fieldKey);
        }
    }
}

public void SetCurrentFieldDefinition(string fieldDefinitionKey)
{
    CurrentFieldDefinitionKey = fieldDefinitionKey;

    if (!string.IsNullOrEmpty(CurrentFieldDefinitionKey) && FieldDefinitionProperties.TryGetValue(CurrentFieldDefinitionKey, out var properties))
    {
        FieldDefinitionUpdate = new FieldDefinitionUpdate {DisplayName = properties.DisplayName};
    }
    else
    {
        FieldDefinitionUpdate = null;
    }
}

The code snippet does the following:

• Fills a list of field definitions of the selected organization.
• Holds a reference to the selected field.
• Holds a reference to the object that is used to update the field.

Create a field definition

To create a field definition, follow these steps:

1. Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
2. Add the following code to the end of the class:

public async Task CreateFieldDefinitionAsync(IFieldDefinitionCreation fieldDefinitionCreation)
{
    var fieldDefinitionDescriptor = await PlatformServices.AssetRepository.CreateFieldDefinitionLiteAsync(CurrentOrganization.Id, fieldDefinitionCreation, CancellationToken.None);
    CurrentFieldDefinitionKey = fieldDefinitionDescriptor.FieldKey;

    Debug.Log($"Field definition {fieldDefinitionCreation.Key} created.");

    await GetFieldDefinitionsAsync();
}

The code snippet does the following:

• Creates a new field definition based on the values specified in the IFieldDefinitionCreation object.
• Displays a success message in the console.

Update a field definition

To update a field definition, follow these steps:

1. Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
2. Add the following code to the end of the class:

public async Task UpdateFieldDefinitionAsync(IEnumerable<string> selectionAcceptedValues)
{
    if (string.IsNullOrEmpty(CurrentFieldDefinitionKey)) return;

    var fieldDefinition = await PlatformServices.AssetRepository.GetFieldDefinitionAsync(new FieldDefinitionDescriptor(CurrentOrganization.Id, CurrentFieldDefinitionKey), CancellationToken.None);

    await fieldDefinition.UpdateAsync(FieldDefinitionUpdate, CancellationToken.None);

    try
    {
        await fieldDefinition.AsSelectionFieldDefinition().SetSelectionValuesAsync(selectionAcceptedValues, CancellationToken.None);
    }
    catch (Exception)
    {
        // Fail silently
    }

    await fieldDefinition.RefreshAsync(CancellationToken.None);
    var properties = await fieldDefinition.GetPropertiesAsync(CancellationToken.None);
    FieldDefinitionProperties[CurrentFieldDefinitionKey] = properties;

    Debug.Log($"Field definition {CurrentFieldDefinitionKey} updated.");
}

The code snippet does the following:

• Updates the selected field definition.
• Displays a success message in the console.

Delete a field definition

To delete a field definition, follow these steps:

1. Open the AssetManagementBehaviour script that you created as described in Get started with Asset SDK.
2. Add the following code to the end of the class:

public async Task DeleteFieldDefinitionAsync(string fieldDefinitionKey)
{
    await PlatformServices.AssetRepository.DeleteFieldDefinitionAsync(new FieldDefinitionDescriptor(CurrentOrganization.Id, fieldDefinitionKey), CancellationToken.None);

    Debug.Log($"Field definition {fieldDefinitionKey} deleted.");

    await GetFieldDefinitionsAsync();
}

The code snippet does the following:

• Deletes the field definition passed as a parameter.
• Refreshes the list of field definitions of the Organization.
• If the deleted field definition was the currently selected one, it sets the current selection to null.
• Displays a success message in the console.

Add a UI for listing and managing field definitions

To create a UI for listing and managing field definitions, follow these steps:

1. In your Unity Project window, go to Assets > Scripts.
2. Select and hold the Assets/Scripts folder.
3. Go to Create > C# Script.
4. Name your script UseCaseManageFieldDefinitionsExampleUI.
5. Open the UseCaseManageFieldDefinitionsExampleUI script that you created in the previous step and replace the contents of the file with the following code sample:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Unity.Cloud.Assets;
using Unity.Cloud.Identity;
using UnityEngine;

public class UseCaseManageFieldDefinitionsExampleUI : IAssetManagementUI
{
    readonly AssetManagementBehaviour m_Behaviour;
    readonly string[] m_FieldTypeList;
    GUIStyle m_ErrorLabelStyle;

    public UseCaseManageFieldDefinitionsExampleUI(AssetManagementBehaviour behaviour)
    {
        m_Behaviour = behaviour;
        m_FieldTypeList = Enum.GetNames(typeof(FieldDefinitionType));
    }

    public void OnGUI() { }
}

6. In the same script, replace the OnGUI function with the following code:

IOrganization m_CurrentOrganization;
FieldDefinitionCreation m_FieldDefinitionCreation = new();
List<string> m_SelectionAcceptedValues = new();
Vector2 m_FieldsScrollPosition;

public void OnGUI()
{
    if (m_ErrorLabelStyle == null)
    {
        m_ErrorLabelStyle = new GUIStyle(GUI.skin.label) {normal = {textColor = Color.red}};
    }

    if (!m_Behaviour.IsOrganizationSelected) return;

    if (m_CurrentOrganization != m_Behaviour.CurrentOrganization)
    {
        m_CurrentOrganization = m_Behaviour.CurrentOrganization;
        _ = m_Behaviour.GetFieldDefinitionsAsync();
    }

    GUILayout.BeginVertical();

    // Go back to select a different scene.
    if (GUILayout.Button("Back"))
    {
        m_Behaviour.SetSelectedOrganization(null);
        return;
    }

    if (GUILayout.Button("Refresh", GUILayout.Width(60)))
    {
        _ = m_Behaviour.GetFieldDefinitionsAsync();
    }

    GUILayout.EndVertical();

    GUILayout.BeginVertical();

    if (GUILayout.Button("Create New"))
    {
        m_Behaviour.SetCurrentFieldDefinition(null);
        m_FieldDefinitionCreation = new FieldDefinitionCreation();
    }

    GUILayout.Label("Fields:");
    ListFieldDefinitions();

    GUILayout.EndVertical();

    GUILayout.BeginVertical();

    if (m_Behaviour.CurrentFieldDefinitionKey == null)
    {
        CreateFieldDefinition();
    }
    else
    {
        DisplayFieldDefinition();
    }

    GUILayout.EndVertical();
}

void ListFieldDefinitions()
{
    if (m_Behaviour.FieldDefinitionProperties.Count == 0)
    {
        GUILayout.Label(" ! No fields !");
        return;
    }

    m_FieldsScrollPosition = GUILayout.BeginScrollView(m_FieldsScrollPosition, GUILayout.MinWidth(Screen.width * 0.2f), GUILayout.Height(Screen.height * 0.8f));

    foreach (var kvp in m_Behaviour.FieldDefinitionProperties)
    {
        GUILayout.BeginHorizontal();

        GUILayout.Label(kvp.Key);

        GUI.enabled = kvp.Key != m_Behaviour.CurrentFieldDefinitionKey;

        if (GUILayout.Button("Select", GUILayout.Width(60)))
        {
            m_Behaviour.SetCurrentFieldDefinition(kvp.Key);
            if (kvp.Value.Type == FieldDefinitionType.Selection)
            {
                m_SelectionAcceptedValues = kvp.Value.AsSelectionFieldDefinitionProperties().AcceptedValues?.ToList() ?? new List<string>();
            }
        }

        GUI.enabled = true;

        if (kvp.Value.IsDeleted)
        {
            GUILayout.Space(64);
        }
        else
        {
            if (GUILayout.Button("Delete", GUILayout.Width(60)))
            {
                _ = m_Behaviour.DeleteFieldDefinitionAsync(kvp.Key);
            }
        }

        GUILayout.EndHorizontal();
    }

    GUILayout.EndScrollView();
}

void CreateFieldDefinition()
{
    GUILayout.Label("New Field Definition (* = required):");

    GUILayout.Label("Field Key *:");
    m_FieldDefinitionCreation.Key = GUILayout.TextField(m_FieldDefinitionCreation.Key).Trim();

    GUILayout.Label("Display Name *:");
    m_FieldDefinitionCreation.DisplayName = GUILayout.TextField(m_FieldDefinitionCreation.DisplayName);

    GUILayout.Label("Type *:");
    var type = (int) m_FieldDefinitionCreation.Type;
    type = GUILayout.SelectionGrid(type, m_FieldTypeList, 3);
    m_FieldDefinitionCreation.Type = Enum.Parse<FieldDefinitionType>(m_FieldTypeList[type], true);

    var isEmpty = string.IsNullOrEmpty(m_FieldDefinitionCreation.Key) || string.IsNullOrEmpty(m_FieldDefinitionCreation.DisplayName);
    var isUnique = !m_Behaviour.FieldDefinitionProperties.ContainsKey(m_FieldDefinitionCreation.Key);

    GUI.enabled = !isEmpty && isUnique;

    if (GUILayout.Button("Create"))
    {
        _ = m_Behaviour.CreateFieldDefinitionAsync(m_FieldDefinitionCreation);
        m_FieldDefinitionCreation = new FieldDefinitionCreation();
    }

    if (!isEmpty && !isUnique)
    {
        GUILayout.Label($"Field {m_FieldDefinitionCreation.Key} already exists.", m_ErrorLabelStyle);
    }

    GUI.enabled = true;
}

void DisplayFieldDefinition()
{
    if (!m_Behaviour.FieldDefinitionProperties.TryGetValue(m_Behaviour.CurrentFieldDefinitionKey, out var properties))
    {
        GUILayout.Label(" ! Field definition properties not loaded !");
        return;
    }

    GUILayout.Label($"Field Definition: {m_Behaviour.CurrentFieldDefinitionKey}");
    GUILayout.Label(properties.IsDeleted ? "Deleted" : "Active");
    GUILayout.Label($"Created on: {properties.AuthoringInfo?.Created:yyyy-M-d dddd}");
    GUILayout.Label($"Updated on: {properties.AuthoringInfo?.Updated:yyyy-M-d dddd}");

    var multiSelectionStatus = string.Empty;
    var acceptedValues = string.Empty;

    if (properties.Type == FieldDefinitionType.Selection)
    {
        var selectionProperties = properties.AsSelectionFieldDefinitionProperties();

        multiSelectionStatus = selectionProperties.Multiselection ? ", Multi" : ", Single";
        acceptedValues = string.Join(',', selectionProperties.AcceptedValues ?? new List<string>());
    }

    GUILayout.Label($"Type: {properties.Type}{multiSelectionStatus}");

    if (properties.IsDeleted)
    {
        GUILayout.Label($"Display name: {properties.DisplayName}");
        if (!string.IsNullOrEmpty(acceptedValues))
        {
            GUILayout.Label($"Accepted values: {acceptedValues}");
        }

        return;
    }

    GUILayout.Space(5f);

    DisplayUpdateValues(m_Behaviour.FieldDefinitionUpdate);

    if (properties.Type == FieldDefinitionType.Selection)
    {
        DisplaySelectionValues();
    }

    GUILayout.Space(5f);
    if (GUILayout.Button("Update"))
    {
        _ = m_Behaviour.UpdateFieldDefinitionAsync(m_SelectionAcceptedValues);
    }
}

static void DisplayUpdateValues(FieldDefinitionUpdate update)
{
    GUILayout.Label("Display name:");
    update.DisplayName = GUILayout.TextField(update.DisplayName);
}

void DisplaySelectionValues()
{
    GUILayout.Space(5f);
    GUILayout.Label("Accepted Values:");

    var value = string.Join(',', m_SelectionAcceptedValues);
    var newValue = GUILayout.TextField(value);
    if (value != newValue)
    {
        m_SelectionAcceptedValues = newValue.Split(',').Select(x => x.Trim()).ToList();
    }
}

7. Open the AssetManagementUI script that you created as described in Get started with Asset SDK and replace the contents of the Awake function with the following code:

m_UI.Add(new OrganizationSelectionExampleUI(m_Behaviour));
m_UI.Add(new UseCaseManageFieldDefinitionsExampleUI(m_Behaviour));

The code snippet does the following:

• Displays a list of the selected Organization's field definitions. Next to each field definition displays a Select and a Delete UI button.
• Displays a UI button to create a new field definition.
• When you select a field definition, additional UI elements display the field definition's information.