Menu déroulant configurable

1. DESCRIPTION GÉNÉRALE

L'administrateur peut créer des éléments d'interface utilisateur de type « Dropdown » (menu déroulant) avec un comportement personnalisé, et les ajouter aux vues. La personnalisation consiste en ce que l'administrateur peut définir, sous la forme d'une requête v2 API, la règle selon laquelle le menu déroulant génère la liste des valeurs qu'il affiche lorsque l'utilisateur clique dessus.

Le cas d'utilisation typique du menu déroulant configurable est celui d'un « sélecteur dépendant ». Cela signifie disposer d'un menu déroulant qui affiche une liste limitée des valeurs du champ concerné, en fonction des valeurs définies pour d'autres champs de la même entité. Cela évite à l'utilisateur d'avoir à faire défiler une longue liste de toutes les valeurs possibles.

Exemple 1 : lorsque l'utilisateur associe une fonctionnalité à un incrément de programme (PI), il souhaite que le menu déroulant « Incrément de programme » ne répertorie que les PI du train de livraison agile (ART) particulier attribué à cette fonctionnalité. L'utilisateur ne souhaite pas faire défiler et deviner parmi tous les PI des ART.

Exemple 2 : lorsque l'utilisateur associe un élément de travail à un résultat clé, il souhaite que le menu déroulant « Résultat clé » n'affiche que les résultats clés de l'objectif auquel cet élément de travail est associé. L'utilisateur ne souhaite pas faire défiler tous les résultats clés dans le système.

2. COMMENT CONFIGURER ET AJOUTER DES MENUS DÉROULANTS

2.1. Qu'est-ce qu'une configuration?

Un cas particulier de personnalisation du comportement du menu déroulant est appelé « configuration » du menu déroulant. Le menu déroulant configurable prend actuellement en charge, et toutes ses configurations peuvent être utilisées dans :

1. Vues détaillées, en tant qu'élément de contrôle déroulant,
2. Vues de liste et listes internes, en tant qu'unité.

Chaque configuration peut être associée à un seul champ d'un type d'entité (types). Ce champ peut être un lien vers une entité par défaut (domaine natif), un lien vers une entité de domaine extensible ou un champ personnalisé de type « Entité Targetprocess ».

Une configuration est en fait un morceau de code, une requête adressée à l'API Configurable Controls qui contient un ensemble d'attributs. Les attributs sont expliqués dans la section Attributs de configuration.

2.2. Création d'une configuration déroulante

Une configuration peut être créée à l'aide d'un mashup.

Créons un exemple de configuration pour résoudre le problème de l'exemple 1 ci-dessus.

Avec le modèle de données SAFe, notre compte dispose, entre autres, des types d'entités suivants :

1. Agile Release Train, ou ART. Il s'agit essentiellement d'une « équipe d'équipes ». Il est implémenté en tant que type d'entité de domaine extensible et est le parent du type d'entité Équipe.
2. Incrément de programme, ou PI. Il s'agit essentiellement d'une itération du travail d'un ART, c'est-à-dire d'une période liée à un ART. Il s'agit d'une version renommée, qui est un type d'entité par défaut.

Par défaut, le menu déroulant « Incrément de programme » affiche une liste des PI de tous les ART présents dans le compte, même si un ART particulier a été attribué à l'entité en question. Il peut être difficile pour l'utilisateur de parcourir toutes les informations personnelles, dont la plupart ne sont pas pertinentes. Cette capture d'écran illustre le problème :

Ajoutons maintenant un mashup avec une configuration qui atténue le problème – voir le code ci-dessous. Cette configuration fait en sorte que le menu déroulant du champ « Incrément de programme » n'affiche que les incréments de programme de l'ART attribué à cette entité particulière (par exemple, une fonctionnalité). En d'autres termes, cela évite à l'utilisateur d'avoir à sélectionner parmi les PI de toutes les ART du compte.

Cette configuration trie également la liste des PI dans le menu déroulant par nom, dans l'ordre décroissant. Compte tenu des conventions de dénomination de ce compte de démonstration particulier, cela signifie que les PI les plus récents apparaîtront en haut de la liste déroulante.

Exemple de code :

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. Ajout d'une configuration déroulante aux vues détaillées

2.4. Ajouter une configuration déroulante à une vue de liste

2.5. Ajouter une configuration déroulante à l'ajout rapide

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. ATTRIBUTS DE CONFIGURATION

3.1. <b>id</b>

3.2. <b>nom</b>

3.3. <b>label</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>champ</b>

1. C'est null lorsqu'aucune valeur n'est définie.
2. Il comporte les paramètres idname et (tous deux obligatoires), ainsi qu'un paramètre resourceType facultatif qui sert à produire la couleur correcte de l'étiquette de l'entité.

Le champ sera utilisé à la fois pour afficher la valeur et pour la mettre à jour lorsqu'une nouvelle option du menu déroulant sera sélectionnée.

Le nom du champ doit être écrit en camel case. 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. BIBLIOTHÈQUE DE CONFIGURATIONS

4.1. Afficher les flux de valeur pertinents pour les ART attribués

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. Afficher les incréments du programme avec leurs projets correspondants

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. Afficher uniquement les utilisateurs appropriés et disponibles pour une répartition du travail

1. avoir au moins une compétence requise dans cette répartition du travail;
2. disposer de disponibilités dans toutes les périodes où cette répartition du travail comporte des demandes, et ces disponibilités doivent avoir une capacité égale ou supérieure à l'ETP requis par cette répartition du travail.

En d'autres termes, le menu déroulant n'affichera que les utilisateurs qui possèdent les compétences requises et disposent d'une capacité suffisante non allouée pendant les périodes nécessaires.

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)"
          }
        })
    })