Membuat kartu konfigurasi untuk langkah

Panduan ini menjelaskan cara membuat kartu konfigurasi yang memungkinkan pengguna menyesuaikan dan memberikan input untuk langkah-langkah di Google Workspace Flows.

Secara umum, untuk membuat kartu konfigurasi, Anda membuat antarmuka kartu seperti yang Anda lakukan untuk add-on Google Workspace lainnya. Untuk mendapatkan bantuan dalam membuat antarmuka kartu konfigurasi, lihat artikel berikut:

  • Card Builder, alat interaktif yang membantu Anda membuat dan menentukan kartu.
  • Kartu dalam dokumentasi referensi API add-on Google Workspace.
  • Card Service, layanan Apps Script yang memungkinkan skrip mengonfigurasi dan membuat kartu.
  • Antarmuka berbasis kartu dalam dokumentasi developer add-on Google Workspace.

Beberapa widget kartu memiliki fungsi dan fitur khusus Alur Kerja Workspace, yang dijelaskan dalam panduan ini.

Menentukan kartu konfigurasi

Tentukan kartu konfigurasi dalam manifes Apps Script dan dalam kode.

Contoh berikut menunjukkan cara membuat kartu konfigurasi yang meminta pengguna memilih ruang Google Chat.

Mengedit file manifes

Dalam file manifes, tentukan workflowElements.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Sample add-on",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

Edit kode

Dalam kode aplikasi, kembalikan kartu.

Apps Script

/**
* Generates and displays a configuration card to choose a Chat space
  */
function onConfigSpacePicker() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

Menyiapkan pelengkapan otomatis untuk widget input

Anda dapat mengonfigurasi pelengkapan otomatis untuk widget SelectionInput guna membantu pengguna memilih dari daftar opsi. Misalnya, jika pengguna mulai mengetik Atl untuk menu yang mengisi kota-kota di Amerika Serikat, elemen Anda dapat menyarankan Atlanta secara otomatis sebelum pengguna selesai mengetik. Anda dapat melengkapi otomatis hingga 100 item.

Saran pelengkapan otomatis dapat berasal dari sumber data berikut:

  • Penyelesaian otomatis sisi server: Saran diisi dari sumber data pihak ketiga atau eksternal yang Anda tentukan.
  • Data Google Workspace: Saran diisi dari sumber Google Workspace, seperti pengguna Google Workspace atau ruang Google Chat.

Pelengkapan otomatis sisi server

Anda dapat mengonfigurasi widget SelectionInput untuk melengkapi otomatis saran dari sumber data eksternal. Misalnya, Anda dapat membantu pengguna memilih dari daftar prospek penjualan dari sistem pengelolaan hubungan pelanggan (CRM).

Untuk menerapkan pelengkapan otomatis sisi server, Anda harus:

  1. Tentukan sumber data: Di widget SelectionInput, tambahkan DataSourceConfig yang menentukan RemoteDataSource. Konfigurasi ini mengarah ke fungsi Apps Script yang mengambil saran pelengkapan otomatis.
  2. Terapkan fungsi pelengkapan otomatis: Fungsi ini dipicu saat pengguna mengetik di kolom input. Fungsi ini harus mengkueri sumber data eksternal Anda berdasarkan input pengguna dan menampilkan daftar saran.

Contoh berikut menunjukkan cara mengonfigurasi widget SelectionInput untuk pelengkapan otomatis di sisi server:

Apps Script

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

Menangani permintaan pelengkapan otomatis

Fungsi yang ditentukan dalam setFunctionName (misalnya, getAutocompleteResults) menerima objek peristiwa saat pengguna mengetik di kolom. Fungsi ini harus:

  1. Periksa event.workflow.elementUiAutocomplete.invokedFunction untuk memastikan nama fungsi cocok dengan yang diharapkan.
  2. Dapatkan input pengguna dari event.workflow.elementUiAutocomplete.query.
  3. Buat kueri sumber data eksternal menggunakan kueri.
  4. Menampilkan hingga 100 saran dalam format yang diperlukan.

Contoh berikut menunjukkan cara menerapkan fungsi handleAutocompleteRequest() untuk menampilkan saran berdasarkan kueri pengguna:

Apps Script

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Pelengkapan otomatis data Google Workspace

Anda juga dapat mengisi saran pelengkapan otomatis dari data dalam lingkungan Google Workspace pengguna:

  • Pengguna Google Workspace: Isi pengguna dalam organisasi Google Workspace yang sama.
  • Ruang Google Chat: Mengisi ruang Google Chat tempat pengguna menjadi anggota.

Untuk mengonfigurasi ini, tetapkan PlatformDataSource di widget SelectionInput, dengan menentukan WorkflowDataSourceType sebagai USER atau SPACE.

Apps Script

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

Contoh: Menggabungkan jenis pelengkapan otomatis

Contoh berikut menunjukkan fungsi onConfig yang membuat kartu dengan tiga widget SelectionInput, yang menunjukkan pelengkapan otomatis sisi server, pengguna, dan ruang:

Apps Script

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  var multiSelect1 =
    CardService.newSelectionInput()
      .setFieldName("value1")
      .setTitle("Server Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setRemoteDataSource(
            CardService.newAction().setFunctionName('getAutocompleteResults')
          )
      )
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setPlatformDataSource(
            CardService.newPlatformDataSource()
              .setHostAppDataSource(
                CardService.newHostAppDataSource()
                  .setWorkflowDataSource(
                    CardService.newWorkflowDataSource()
                      .setIncludeVariables(true)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

Fitur khusus Workspace Flows

Beberapa widget kartu memiliki fungsi dan fitur khusus Alur Kerja Workspace, yang dijelaskan di sini.

TextInput dan SelectionInput

Widget TextInput dan SelectionInput memiliki fitur khusus Alur Kerja Workspace berikut:

  • includeVariables: Properti boolean yang memungkinkan pengguna memilih variabel dari langkah sebelumnya.
  • type: Nilai yang di-enum yang melengkapi otomatis saran. Nilai yang didukung meliputi:
    • USER: Memberikan saran pelengkapan otomatis untuk orang-orang dalam kontak pengguna.
    • SPACE: Memberikan saran pelengkapan otomatis untuk ruang Google Chat tempat pengguna menjadi anggotanya.

Jika includeVariables dan type ditetapkan, kolom input akan menggabungkan pengalaman keduanya. Pengguna dapat memilih variabel type yang cocok dari menu drop-down, dan melihat saran pelengkapan otomatis untuk variabel tersebut.

  • Saran pelengkapan otomatis untuk ruang Google Chat.
    Gambar 1: Pengguna meninjau saran pelengkapan otomatis saat memilih ruang.
  • Menu variabel memungkinkan pengguna memilih variabel output dari langkah sebelumnya.
    Gambar 2: Pengguna memilih variabel output dari langkah sebelumnya dari drop-down ➕Variabel.

Pertimbangan dan batasan kartu

  • Navigasi kartu seperti popCard(), pushCard(), dan updateCard() tidak didukung di add-on yang memperluas Alur.

  • Saat SelectionInput digunakan di pemilih variabel, widget hanya mendukung "type": "MULTI_SELECT". Di tempat lain dalam kartu konfigurasi, SelectionInput mendukung semua nilai SelectionType.