Ejercicio: Extensión de conexiones Microsoft Viva con extensiones de tarjeta adaptable

  • 12 minutos

En este ejercicio, creará una Extensión de tarjeta adaptable (ACE) para mostrar el último anuncio importante de la empresa. Agregará la ACE al panel para que se muestre en la experiencia móvil y de escritorio de Conexiones Viva.

Crear una nueva solución

Para empezar, cree una nueva solución utilizando el generador de Yeoman de SharePoint Framework.

  1. Crear una carpeta para el proyecto denominado spfx-company-announcements-ace
  2. En un terminal, cambiar el directorio de trabajo a spfx-company-announcements-ace
  3. A continuación, ejecutar el comando yo @microsoft/sharepoint para iniciar scaffolding de una nueva solución
  4. Mensajes del generador de respuestas:
    1. ¿Cuál es el nombre de la solución?: spfx-company-announcements-ace
    2. Solo se admite SharePoint Online (más reciente). Para versiones anteriores de SharePoint (2016 y 2019) use la versión 1.12.1 del generador. Solo SharePoint Online (versiones más recientes)
    3. ¿Dónde desea ubicar los archivos? Use la carpeta actual.
    4. ¿Desea permitir que el administrador de inquilinos pueda implementar la solución en todos los sitios inmediatamente sin ejecutar ninguna implementación de características ni agregar aplicaciones en sitios? No
    5. ¿Los componentes de la solución necesitarán permisos para acceder a las API web que son exclusivas y no se compartirán con otros componentes en el espacio empresarial?: No
    6. ¿Cuál es el tipo de componente del lado cliente que se va a crear? Extensión de tarjeta adaptable
    7. ¿Qué plantilla quiere usar? Plantilla de tarjeta básica
    8. ¿Cuál es el nombre de su extensión de tarjeta adaptable? Anuncios importantes
    9. ¿Cuál es la descripción del elemento web? Muestra anuncios importantes de la empresa
  5. Espere a que se complete la creación de proyecto. Puede tardar unos minutos

    Sugerencia

    Al crear el proyecto, es probable que vea algunas advertencias. Puede omitirlas sin problemas.

Instalar el certificado de desarrollo

SharePoint Framework usa un área de trabajo hospedada en SharePoint Online para permitirle probar el código antes de implementarlo en Conexiones Viva. Al probar el código, se inicia un servidor web local con Gulp. El área de trabajo de SharePoint Framework carga los archivos del servidor local y le permite probarlos. Para permitir que el área de trabajo cargue archivos desde el servidor de desarrollo local, debe confiar en el certificado de desarrollo proporcionado por SharePoint Framework.

Importante

Solo debe instalar una vez el certificado de desarrollo en el equipo. Al crear un nuevo proyecto, SharePoint Framework usará el certificado instalado anteriormente. Si ya lo ha hecho, puede omitir estos pasos.

  1. Abra un terminal.
  2. Cambie el directorio de trabajo a la carpeta del proyecto.
  3. Ejecute el comando gulp trust-dev-cert
  4. Seguir las instrucciones que aparecen en pantalla para completar la instalación del certificado

Editar el código de la extensión de tarjeta adaptable

Después de agregar una extensión de tarjeta adaptable a la solución, el siguiente paso es implementar su código para que muestre el último anuncio importante.

Cargar el anuncio más reciente

Para empezar, extienda el código de ACE para cargar el último anuncio de la lista Anuncios.

  1. En el editor de código, abrir el proyecto

  2. Abrir el archivo ./src/adaptiveCardExtensions/importantAnnouncements/ImportantAnnouncementsAdaptiveCardExtension.ts

  3. A la lista de importaciones, agregar import { SPHttpClient } from '@microsoft/sp-http';

  4. Agregar una interfaz para definir la forma de los datos del anuncio

    export interface IAnnouncement {
  title: string;
  url: string;
}

  5. Actualizar la interfaz IImportantAnnouncementsAdaptiveCardExtensionState para almacenar información sobre el anuncio recuperado

    export interface IImportantAnnouncementsAdaptiveCardExtensionState {
  announcement: IAnnouncement | undefined;
}

  6. Actualice el método onInit para establecer el estado inicial de la tarjeta e inicializar los anuncios de carga.

    public onInit(): Promise<void> {
  this.state = {
    announcement: undefined
  };

  this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
  this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());

  return this._fetchAnnouncements();
}

  7. Implemente el método _fetchAnnouncements que carga los anuncios de la empresa de la lista.

    private _fetchAnnouncements(): Promise<void> {
  return this.context.spHttpClient
    .get(`${this.context.pageContext.web.absoluteUrl}/_api/web/lists/getByTitle('Announcements')/items?$filter=Important eq 1&$select=Title,ID`,
      SPHttpClient.configurations.v1,
      {
        headers: {
          'accept': 'application/json;odata.metadata=none'
        }
      })
    .then(response => response.json())
    .then(announcements => {
      const announcement = announcements.value.pop();
      this.setState({
        announcement: {
          title: announcement.Title,
          url: `${this.context.pageContext.web.absoluteUrl}/lists/Announcements/DispForm.aspx?ID=${announcement.ID}`
        }
      });
    })
    .catch(error => console.error(error));
}

    El método usa el spHttpClient para recuperar anuncios importantes de la lista Anuncios. spHttpClient ajusta la API fetch estándar y se autentica para llamar a las API de SharePoint. En la dirección URL de la API, se usa el parámetro OData $select para especificar la lista de propiedades que se va a recuperar. Estas propiedades coinciden con las columnas de la lista Anuncios. Al llamar a la API de SharePoint, también establece el encabezado accept para suprimir los metadatos de la respuesta. Le permite minimizar la cantidad de datos enviados a través de la red. Después de que el método recupere los datos, obtiene el último anuncio y lo asigna para que lo muestre la ACE.

  8. El último paso es cambiar el icono de la tarjeta a un triángulo de advertencia en el captador iconProperty:

    protected get iconProperty(): string {
  return 'warning';
}

Mostrar el título del anuncio en la tarjeta

Después de implementar el código para recuperar el último anuncio importante de la lista, el siguiente paso es mostrarlo en la tarjeta.

  1. En el editor de código, abrir el archivo ./src/adaptiveCardExtensions/importantAnnouncements/cardView/CardView.ts

  2. En la clase CardView, actualice el captador data para asignar el título del anuncio al texto principal de la tarjeta.

    public get data(): IBasicCardParameters {
  return {
    primaryText: this.state.announcement.title
  };
}

  3. A continuación, actualice el captador cardButtons para que apunte a la dirección URL del anuncio:

    public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: 'View',
      action: {
        type: 'ExternalLink',
        parameters: {
          target: this.state.announcement.url
        }
      }
    }
  ];
}

  4. Por último, actualice el controlador de eventos onCardSelection para que también apunte a la dirección URL del anuncio:

    public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
  return {
    type: 'ExternalLink',
    parameters: {
      target: this.state.announcement.url
    }
  };
}

    Con estos cambios, la tarjeta mostrará un botón para ver los detalles del anuncio en la lista de SharePoint, pero también al seleccionar la tarjeta en sí se abrirá el anuncio.

Probar la extensión de tarjeta adaptable en el área de trabajo

Para probar las extensiones de tarjeta adaptables en el área de trabajo:

  1. Abrir el terminal y cambiar el directorio de trabajo a la carpeta del proyecto
  2. Ejecutar el comando gulp serve --nobrowser para iniciar el servidor web local:

    Advertencia

    Si ve en el terminal la siguiente advertencia: Captura de pantalla de una ventana de terminal que muestra una advertencia después de ejecutar el comando gulp serve

    Advertencia: [spfx-serve] Al servir en modo HTTPS, se debe proporcionar una ruta de acceso de certificado PFX o una ruta de acceso de certificado y una ruta de acceso de clave, o bien se debe generar y confiar en un certificado de desarrollo. Si no se proporciona un certificado SSL, se usará un certificado autofirmado predeterminado. Espere advertencias de seguridad del explorador.

    significa que el servidor web local no pudo cargar el certificado de desarrollo. Para solucionar este problema, detenga el servidor web presionando CTRL+C y ejecute el comando gulp trust-dev-cert.

  3. En un explorador web, vaya al área de trabajo en <Home site url>/_layouts/workbench.aspx. La dirección URL del sitio principal es donde creó la lista Anuncios en el ejercicio anterior.

    Advertencia

    Después de abrir el área de trabajo, si ve el siguiente error: SharePoint Workbench muestra un mensaje de advertencia sobre la imposibilidad de cargar el manifiesto local.

    El elemento web no aparecerá en el cuadro de herramientas. Asegúrese de que "gulp serve" se ejecuta en un proyecto de elemento web. Actualice la página una vez que se esté ejecutando "gulp serve".

    significa que el servidor web local no pudo cargar el certificado de desarrollo. Para solucionar este problema, detenga el servidor web presionando CTRL+C y ejecute el comando gulp trust-dev-cert.

  4. Para agregar la Extensión de tarjeta adaptable recién creada en el lienzo, seleccione el botón + para iniciar el cuadro de herramientas. Flecha roja que apunta al botón + con el cuadro de herramientas de elementos web abierto en el área de trabajo SharePoint.
  5. En la barra de búsqueda, escriba Important announcements y seleccione la Extensión de tarjeta adaptable. Los anuncios importantes de la Extensión de tarjeta adaptable resaltada en el cuadro de herramientas del área de trabajo de SharePoint.
  6. En las opciones de vista del área de trabajo, elija Vista previa para salir del modo de edición e interactuar con la flecha roja extensión de tarjeta adaptable que apunta a la opción Vista previa en el área de trabajo de SharePoint.
  7. Al seleccionar la tarjeta o el botón Ver, se le redirigirá a la lista de SharePoint para ver el anuncio. Flecha roja que apunta desde la Extensión de tarjeta adaptable al elemento de lista de anuncios que se muestra en un explorador web.
  8. Para detener las pruebas, vaya al terminal y presione CTRL+C para detener el servidor web local.

Después de comprobar que la extensión de tarjeta adaptable recién agregada funciona según lo previsto, la implementará en Conexiones Viva.

Implementación de la extensión de tarjeta adaptable en conexiones Viva

Ha creado la Extensión de tarjeta adaptable Important announcements mediante el SharePoint Framework. Ahora vamos a implementarlo en Conexiones Viva.

Empaquetar la aplicación

Para empaquetar la Extensión de tarjeta adaptable en una aplicación con Gulp:

  1. Vaya al terminal donde el directorio de trabajo es la carpeta raíz del proyecto
  2. Para compilar la solución en modo de versión, ejecute el comando gulp bundle --ship.
  3. Para crear un paquete de modo de versión de la solución, ejecute el comando gulp package-solution --ship
  4. La tarea package-solution creó un archivo de paquete de aplicación denominado spfx-company-announcements-ace.sppkg en la carpeta ./sharepoint/solution.

Este archivo forma parte del paquete de la aplicación. A continuación, implementará este paquete en el catálogo de aplicaciones de SharePoint, que contiene todas las extensiones de Conexiones Viva.

Crear un sitio de catálogo de aplicaciones

Si no tiene un catálogo de aplicaciones en el espacio empresarial, tendrá que crearlo antes de continuar con este ejercicio.

  1. En un explorador web, vaya al Centro de administración de Microsoft 365 ubicado en https://admin.microsoft.com.
  2. En el menú lateral, seleccione la opción Mostrar todo.
  3. En la lista de Centros de administración, seleccione SharePoint
  4. En el Centro de administración de SharePoint, en la navegación lateral, seleccione Más características
  5. En la sección Aplicaciones, seleccione el botón Abrir para ir a la página de administrador de Aplicaciones
  6. En Aplicaciones, seleccione Catálogo de aplicaciones
  7. Si el sitio se abre, ya tiene un catálogo de aplicaciones y puede omitir más pasos
  8. Si el catálogo de aplicaciones no existe, se le pedirá que cree uno.
  9. En la lista de opciones, elija Crear automáticamente un nuevo sitio de catálogo de aplicaciones y seleccione Aceptar.

Implementar la aplicación en el catálogo de aplicaciones de SharePoint

Para implementar la aplicación en el catálogo de aplicaciones:

  1. En un explorador web, vaya al catálogo de aplicaciones de SharePoint
  2. En el catálogo de aplicaciones de SharePoint, en la navegación lateral, elija Aplicaciones para SharePoint
  3. Cargar/arrastrar y colocar el archivo spfx-company-announcements-ace.sppkg en la lista
  4. SharePoint le pedirá que confirme e implemente el paquete. Hace que el paquete esté disponible para instalarse en el sitio de SharePoint. Catálogo de aplicaciones de SharePoint para confirmar la implementación del paquete de solución cargado.
  5. Seleccione Implementar

Instalar la aplicación en el Sitio principal

Una vez que la aplicación se implemente correctamente en el catálogo de aplicaciones, tendrá que instalarla en el Sitio principal.

Para instalar la aplicación:

  1. En un explorador web, vaya al Sitio principal
  2. En la navegación superior, seleccione el icono Configuración (engranaje).
  3. En la sección SharePoint, seleccione el vínculo Agregar una aplicación. Se le mostrará la página Mis aplicaciones
  4. En el cuadro de búsqueda de la página, escriba Company y busque la aplicación spfx-company-announcements-ace-client-side-solution
  5. Para instalar la aplicación, seleccione el botón Agregar

La Extensión de tarjeta adaptable de la aplicación ahora estará disponible para agregarla al panel.

Vista previa de la extensión de tarjeta adaptable en Conexiones Viva

Después de implementar el nuevo paquete de solución con la extensión de tarjeta adaptable, lo último que queda es probarlo en el escritorio de Conexiones Viva.

Adición de la extensión de tarjeta adaptable al panel conexiones Viva

Para agregar la extensión de tarjeta adaptable anuncios importantes al panel conexiones Viva:

  1. En un explorador web, vaya al Sitio principal en su cuenta empresarial de Microsoft 365
  2. En el menú sitio, seleccione Páginas
  3. En la lista de páginas, seleccione Dashboard.aspx
  4. En el menú página, elija Editar
  5. En el lienzo, elija el botón Agregar una tarjetaPuntero del mouse que mantiene el puntero sobre el botón Agregar una tarjeta en la página del panel.
  6. En el cuadro de búsqueda, escriba Important announcements y, en la lista de resultados de la búsqueda, seleccione la Extensión de tarjeta adaptable de Anuncios importantes
  7. Para guardar los cambios en el panel, en el menú de página, elija Volver a publicar

Extensión de tarjeta adaptable en versión preliminar en el escritorio de Conexiones Viva

Después de agregar la extensión de tarjeta adaptable al panel, puede obtener una vista previa de ella en el escritorio de Conexiones Viva.

  1. Abra el escritorio de Microsoft Teams o en un explorador web navegue por https://teams.microsoft.com
  2. En el carril izquierdo, elija la aplicación Conexiones Viva .
  3. Vea la extensión de tarjeta adaptable anuncios importantes visible en el panel El panel resaltado en la experiencia de escritorio de Conexiones Viva.

Extensión de tarjeta adaptable en versión preliminar en El móvil de Conexiones Viva

Después de agregar la extensión de tarjeta adaptable al panel, también es visible en la experiencia móvil de Conexiones Viva. Para obtener una vista previa de él:

  1. En el dispositivo móvil, abra la aplicación Microsoft Teams
  2. En la lista de aplicaciones, elija la aplicación Conexiones Viva .
  3. Vea la extensión de tarjeta adaptable anuncios importantes visible en el panel del panel que se muestra en la aplicación móvil Conexiones Viva.