Menú desplegable configurable

1. DESCRIPCIÓN GENERAL

El administrador puede crear elementos de interfaz de usuario del tipo «menú desplegable» con un comportamiento personalizado y añadirlos a las vistas. La personalización consiste en que el Administrador puede definir, en forma de solicitud v2 API, la regla por la cual el menú desplegable genera la lista de valores que muestra cuando el Usuario hace clic en él.

El caso de uso típico del menú desplegable configurable es tener un «selector dependiente». Esto significa tener un menú desplegable que muestre una lista limitada de los valores del campo respectivo, dependiendo de los valores establecidos para otros campos de la misma entidad. Esto evita que el usuario tenga que desplazarse por una larga lista de todos los valores posibles.

Ejemplo 1: Cuando el usuario vincula una característica a un incremento de programa (PI), desea que el menú desplegable «Incremento de programa» solo muestre los PI del tren de lanzamiento ágil (ART) concreto asignado a esta característica. El usuario no quiere desplazarse por todos los PI de ART y adivinar cuál es el suyo.

Ejemplo 2: Cuando el usuario vincula un elemento de trabajo a un resultado clave, desea que el menú desplegable «Resultado clave» solo muestre los resultados clave del objetivo al que está vinculado este elemento de trabajo. El usuario no quiere desplazarse por todos los resultados clave del sistema.

2. CÓMO CONFIGURAR Y AÑADIR MENÚS DESPLEGABLES

2.1. ¿Qué es una configuración?

Un caso concreto de personalización del comportamiento del menú desplegable se denomina «configuración» del menú desplegable. El menú desplegable configurable es compatible actualmente con, y su configuración se puede utilizar en:

1. Vistas detalladas, como elemento de control desplegable,
2. Vistas de lista y listas internas, como una unidad.

Cada configuración puede asociarse únicamente a un campo de un tipo de entidad (tipos). Este campo puede ser un enlace a una entidad predeterminada (dominio nativo), un enlace a una entidad de dominio ampliable o un campo personalizado de tipo «Entidad de proceso de destino».

Una configuración es, de hecho, un fragmento de código, una solicitud a la API de controles configurables que contiene un conjunto de atributos. Los atributos se explican en la sección Atributos de configuración.

2.2. Creación de una configuración desplegable

Se puede crear una configuración con una combinación.

Creemos una configuración de ejemplo para resolver el problema del ejemplo 1 anterior.

Con el modelo de datos SAFe, nuestra cuenta tiene, entre otras cosas, los siguientes tipos de entidades:

1. Agile Release Train, o ART. Básicamente, se trata de un «equipo de equipos». Se implementa como un tipo de entidad de dominio extensible y es padre del tipo de entidad Equipo.
2. Incremento del programa, o PI. Se trata básicamente de una iteración del trabajo de un ART, es decir, un periodo de tiempo vinculado a un ART. Es una versión renombrada, que es un tipo de entidad predeterminado.

De forma predeterminada, el menú desplegable «Incremento del programa» muestra una lista de los PI de todos los ART presentes en la cuenta, incluso si se ha asignado un ART concreto a la entidad en cuestión. Puede resultar difícil para el usuario examinar todas las PI, la mayoría de las cuales son irrelevantes. Esta captura de pantalla ilustra el problema:

Ahora añadamos un mashup con una configuración que alivie el problema; véase el código siguiente. Esta configuración hace que el menú desplegable del campo «Incremento del programa» solo muestre los incrementos del programa del ART asignado a esta entidad concreta (por ejemplo, una función). En otras palabras, evita que el usuario tenga que seleccionar entre los PI de todas las ART de la cuenta.

Esta configuración también ordena la lista de PI en el menú desplegable por nombre en orden descendente. Dadas las convenciones de nomenclatura de esta cuenta demo en particular, esto significa que los PI más recientes aparecerán en la parte superior de la lista desplegable.

Código de ejemplo:

tau.mashups
    .addDependency('tau/api/configurable-controls/controls/v1')
    .addMashup(( controlsApiV1 ) => {
        controlsApiV1.addConfiguration('dropdown', {
          id: 'dd_conf_01',
		  name: 'Program Increments of the assigned ART',
          label: 'Program Increment',
          supportedEntityTypes: ['feature'],
          requiredEntityFields: ['id', 'name', 'release'],
          sampleData: {
            release: { name: 'Program Increment' }
          },
          entityClickBehavior: 'openEntity',
          field: 'release',
          dropdownItemsSource: {
            type: 'interpolatedQuery',
            query: "release?where=(agileReleaseTrain.id==${{agileReleaseTrain.id}}$)&orderBy=name desc"
          }
        })
    })

footerPlaceholder

2.3. Añadir una configuración desplegable a las vistas detalladas

2.4. Añadir una configuración desplegable a una vista de lista

2.5. Añadir una configuración desplegable a la adición rápida

tau.mashups
    .addDependency('tau/api/configurable-controls/controls/v1')
    .addMashup(( controlsApiV1 ) => {
        controlsApiV1.addConfiguration('dropdown', {
          id: 'dd_conf_01',
          name: 'Program Increments of the assigned ART',
          label: 'Program Increment',
          supportedEntityTypes: ['feature'],
          requiredEntityFields: ['id', 'name', 'release'],
          allowReset:false,
          sampleData: {
            release: { name: 'Program Increment' }
          },
          entityClickBehavior: 'openEntity',
          field: 'release',
          dropdownItemsSource: {
            type: 'custom',
            getItems: async ({entity}) => {
                const artId = entity.agilereleasetrain || (entity.agileReleaseTrain && entity.agileReleaseTrain.id) || null
                const response = await fetch(___PROTECTED_5___);
                const {items} = await response.json();
                return items;
              }
            //type: 'interpolatedQuery',
            //query: "release?where=(agileReleaseTrain.id==${{agileReleaseTrain.id}}$)&orderBy=name desc"
            }
        })
    })

3. ATRIBUTOS DE CONFIGURACIÓN

3.1. <b>id</b>

3.2. <b>nombre</b>

3.3. <b>etiqueta</b>

3.4. <b>supportedEntityTypes</b>

3.5. <b>allowedLocations</b>

allowedLocations: {
  listUnit: false,
  detailedView: true,
  quickAdd: true,
}

3.6. <b>requiredEntityFields</b>

requiredEntityFields: [
    'id', 
    'name', 
    'feature:{id:feature.id,name:feature.name,projectId:feature.project.id}', 
    'tasks:tasks.select({id,name})',
    'customFieldName: {id:CustomValues.Entity("Custom Field Name").id, name:CustomValues.Entity("Custom Field Name").name, resourceType:"entityTypeName"}'
]

3.7. <b>sampleData</b>

sampleData: {
  id: 5,
  name: 'Some name',
  feature: {id: 10, name: 'Some feature name', projectId: 50},
  tasks: [
    {id: 18, name: 'Task 1'},
    {id: 19, name: 'Task 2'}
  ]
}

3.8. <b>isEnabled</b>

isEnabled?: {
    callback: (info: ConfigurableControlInfo) => boolean | PromiseLike<boolean>;
    rerunOnRequiredFieldsChanged: string[];
  }

isEnabled: {
    callback: info => info.entity.name.toLowerCase().startsWith('s'),
    rerunOnRequiredFieldsChanged: ['name']
}

isEnabled: { 
    callback: () => false, 
    rerunOnRequiredFieldsChanged: [] 
}

3.9. <b>entityClickBehavior</b>

3.10. <b>campo</b>

1. Es null cuando no se establece ningún valor.
2. Tiene los parámetros idname y (ambos obligatorios), y un parámetro resourceType opcional que se utiliza para producir el color correcto de la etiqueta de la entidad.

El campo se utilizará tanto para mostrar el valor como para actualizarlo cuando se seleccione una nueva opción del menú desplegable.

El nombre del campo debe escribirse en mayúsculas y minúsculas. E.g. userStory.

3.11. <b>allowReset</b>

3.12. <b>dropdownItemsSource</b>

dropdownItemsSource:
    | {
        type: 'interpolatedQuery';
        query: string;
      }
    | {
        type: 'custom';
        getItems: (info: ConfigurableControlInfo) => PromiseLike<{id: any; name: string}[]>;
      };

getItems: async info => {
  const response = await fetch(___PROTECTED_17___);
  const items = await response.json();
  return items;
}

3.13. <b>showSearch</b>

4. BIBLIOTECA DE CONFIGURACIONES

4.1. Mostrar flujos de valor relevantes para los ART asignados

tau.mashups
    .addDependency('tau/api/configurable-controls/controls/v1')
    .addMashup(controlsApiV1 => {
        controlsApiV1.addConfiguration('dropdown', {
            id: 'feature_valuestream_filtered_by_assigned_art',
            name: 'Value Stream filtered by ART',
            label: 'Value Stream',
            supportedEntityTypes: ['feature'],
            requiredEntityFields: ['valueStream'],
            sampleData: {
                valueStream: { resourceType: 'valuestream', name: 'Value Stream' }
            },
            entityClickBehavior: 'openDropdown',
            field: 'valueStream',
            dropdownItemsSource: {
                type: 'interpolatedQuery',
                query: "valuestream?where=(valueStreamAgileReleaseTrains.count(${{agileReleaseTrain.id}}$ == null or agileReleaseTrain.id == ${{agileReleaseTrain.id}}$) > 0)&take=999"
            }
        })
    })

4.2. Mostrar incrementos del programa con sus proyectos correspondientes

tau.mashups
    .addDependency('tau/api/configurable-controls/controls/v1')
    .addDependency('tau/configurator')
    .addMashup(( controlsApiV1, configurator ) => {
        const store2 = configurator.getStore2();
        controlsApiV1.addConfiguration('dropdown', {
          id: 'dd_conf_03',
          name: 'PI with Project',
          label: 'PI w/ Project',
          supportedEntityTypes: ['teamiteration'],
          requiredEntityFields: ['release'],
          sampleData: {
            release: {name: 'Program Increment', resourceType: 'release'}
          },
          entityClickBehavior: 'openEntity',
          field: 'release',
          dropdownItemsSource: {
            type: 'custom',
            getItems: async () => {
                const releasesWithProjects = await store2.findAll('release?select={id,name,projectName:project.name}&where=(IsCurrent == True)&orderBy=name desc');
                return releasesWithProjects.map(release => ({
                    id: release.id,
                    name: ___PROTECTED_19___
                }));
            }
          }
        });
    })

4.3. Mostrar solo los usuarios adecuados y disponibles para una asignación de trabajo

1. Tener al menos una de las habilidades requeridas en esta asignación de trabajo
2. Tener disponibilidad en todos los periodos en los que esta asignación de trabajo tiene demanda, y que dicha disponibilidad tenga una capacidad igual o superior al FTE requerido por esta asignación de trabajo.

En otras palabras, el menú desplegable solo mostrará los usuarios que tengan la habilidad necesaria y suficiente capacidad no asignada en los periodos necesarios.

tau.mashups
    .addDependency('tau/api/configurable-controls/controls/v1')
    .addMashup(( controlsApiV1 ) => {
        controlsApiV1.addConfiguration('dropdown', {
          id: 'dd_conf_04',
          name: 'Connected User',
          label: 'Connected User',
          supportedEntityTypes: ['WorkAllocation'],
          requiredEntityFields: ['connectedUser:connectedUser==null?null:{id:connectedUser.id,name:connectedUser.fullName,resourceType:connectedUser.resourceType}'],
          sampleData: {
            ConnectedUser: { name: 'John Smith' }
          },
          entityClickBehavior: 'openEntity',
          field: 'connectedUser',
          dropdownItemsSource: {
            type: 'interpolatedQuery',
            query: "user?select={id, fullname as name}&where=(Skills.Where(name==\"${{Skill.Name}}$\").Count()>0 and Availabilities.Where(Timeframe.Id in [${{Demands.Select(Timeframe.Id)}}$]).Count()==${{Demands.Count()}}$ and Availabilities.Where(Timeframe.Id in [${{Demands.Select(Timeframe.Id)}}$]).Where((AvailableCapacity/100)<${{CustomValues.Get(\"FTE\").Value}}$).Count()==0)"
          }
        })
    })