إنشاء خطوة

يشرح هذا الدليل كيفية إنشاء خطوة يمكن للمستخدمين إضافتها إلى تدفق في Google Workspace Flows.

الخطوة هي خطوة واحدة في تسلسل مهام سير العمل. لا يمكن للخطوات بدء تدفق.

على سبيل المثال، لنفترض أنّ هناك خطوة تتضمّن عمليات حسابية. يطلب هذا البرنامج من المستخدم إدخال قيمتين وعملية حسابية. ثم تجري العملية الحسابية على القيم وتعرض النتيجة.

يضبط المستخدم خطوة الآلة الحاسبة كجزء من مسار.

الشكل 1: يضبط المستخدم خطوة الآلة الحاسبة كجزء من مسار.

لإنشاء خطوة، عليك ضبطها في ملف بيان الإضافة، وكتابة منطق التطبيق في رمز إضافة Google Workspace، ثم نشر الخطوة واختبارها. أثناء الإصدار الأوّلي، لا تنشر إضافة توسّع نطاق "التدفقات".

تحديد الخطوة

لضبط إعدادات خطوة، عليك تحديدها في ملف البيان وكتابة منطق التطبيق الخاص بها في الرمز.

تحديد الخطوة في ملف البيان

في ملف البيان، appsscript.json:

  1. اضبط onConfigFunction وonExecuteFunction على أسماء الدوال المقابلة في رمز الإضافة. في هذا المثال، يُطلق على الدالتين الاسمان onConfigCalculate() وonExecuteCalculate().
    • تتولّى onConfigFunction إعداد الخطوة وضبطها. إذا لزم الأمر، يجمع هذا الإجراء البيانات اللازمة من المستخدمين لتنفيذ الخطوة، مثل العنوان الذي سيتم إرسال رسالة إلكترونية إليه. في مثال هذا الدليل، نطلب إدخال قيمتين وعملية حسابية.
    • ينفّذ onExecuteFunction الخطوة. إذا تم جمع البيانات من المستخدمين، يتم تمرير هذه البيانات إلى هذه الدالة. تعرض هذه السمة مخرجات، إذا كان ذلك منطبقًا. في مثال هذا الدليل، يتم عرض نتيجة عملية حسابية.

  2. اضبط المدخلات والمخرجات المطلوبة، ما يتيح للخطوة جمع البيانات وإرسالها إلى الخطوات اللاحقة. في هذا المثال، اطلب من المستخدم إدخال قيمتين وعملية رياضية محدّدة في inputs[]. إخراج النتيجة المحسوبة على النحو المحدّد في outputs[]

    لمزيد من المعلومات عن المدخلات والمخرجات، راجِع متغيّرات الإدخال و متغيّرات الإخراج. لضمان تشغيل التدفقات بدون حدوث أخطاء، عليك التحقّق من صحة متغيّرات الإدخال.

في ما يلي ملف البيان لخطوة "الآلة الحاسبة":

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Calculator",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

بعد ذلك، اكتب الرمز البرمجي الداعم عن طريق تحديد الخطوة في الرمز البرمجي.

تحديد الخطوة في الرمز

في رمز التطبيق، اتّبِع الخطوات التالية:

  1. اكتب onConfigFunction، ويُطلق عليه onConfigCalculate() في هذا المثال. عندما يضيف المستخدمون الخطوة إلى مسار، يمكنهم ضبط جوانب الخطوة في أداة إنشاء المسار. لجمع المعلومات المطلوبة من المستخدم، يحدّد onConfigFunction بطاقة إعداد.

    البطاقات هي اللبنات الأساسية لواجهات المستخدم في الإضافات. تتيح البطاقات استخدام تنسيق محدّد وعناصر تفاعلية في واجهة المستخدم، مثل الأزرار، بالإضافة إلى الوسائط الغنية، مثل الصور. البطاقات هي الطريقة التي يمكنك من خلالها الحصول على بيانات من مستخدم يحتاج إلى تنفيذ الخطوة، مثل عنوان بريد إلكتروني لإرسال رسالة إلكترونية.

    تعرض OnConfigFunction عنصر RenderActions يحتوي على بطاقة. تحدّد هذه البطاقة واجهة المستخدم التي يضبط فيها المستخدمون بيانات الخطوة. في هذا المثال، ينشئ onConfigFunction بطاقة تطلب من المستخدم إدخال قيمتين وعملية حسابية.

  2. اكتب onExecuteFunction الذي يُسمى onExecuteCalculate() في هذا المثال. عند تنفيذ خطوتك في سير عمل، يتم تنفيذ OnExecuteFunction. يتم تمرير أي قيم إدخال يضبطها المستخدم أثناء الإعداد كما هو محدّد في onConfigurationFunction إلى OnExecuteFunction.

    اكتب OnExecuteFunction() لتنفيذ مهمته بشكل متزامن باستخدام المدخلات المقدَّمة. تذكَّر أنّ OnExecuteFunction() يجب أن تعرض جميع النتائج المحدّدة في بيان سير العمل، وإلا سيحدث خطأ.

يتضمّن نموذج الرمز البرمجي هذا دالة مساعِدة، outputVariables()، تنشئ المتغيّرات المقدَّمة وترسلها كناتج من الخطوة.

خطوتك جاهزة للاختبار.

في ما يلي رمز خطوة "الآلة الحاسبة":

برمجة التطبيقات

/**
 * Generates and displays a configuration card for the sample calculation step.
 *
 * This function creates a card with input fields for two values and a drop-down
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1",
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation",
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2",
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

/**
 * Returns output variables from a step.
 *
 * This function constructs an object that, when returned, sends the
 * provided variable values as output from the current step.
 * The variable values are logged to the console for debugging purposes.
 */
function outputVariables(variableValues) {
  var renderAction =  {
    "hostAppAction" : {
      "workflowAction" : {
        "returnOutputVariablesAction" : {
          "variables" : variableValues
        }
      }
    }
  };
  console.log("renderAction: " + JSON.stringify(renderAction));
  return renderAction;
}

/**
 * Executes the calculation step based on the inputs from a flow event.
 *
 * This function retrieves input values and the operation from the flow event,
 * performs the calculation, and returns the result as an output variable.
 * The function logs the event for debugging purposes.
 */
function onExecuteCalculate(event) {
  console.log("output: " + JSON.stringify(event));
  var calculatedValue = 0;
  var value1 = event.workflow.actionInvocation.inputs["value1"].integerValues[0];
  var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
  var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];

  if (operation == "+") {
    calculatedValue = value1 + value2;
  } else if (operation == "-") {
    calculatedValue = value1 - value2;
  } else if (operation == "x") {
    calculatedValue = value1 * value2;
  } else if (operation == "/") {
    calculatedValue = value1 / value2;
  }
  return outputVariables([{
    "variableId": "result",
    "variableData": {
        "integerValues": [
          calculatedValue
        ]
      },
  }]);
}

اختبار الخطوة

لاختبار خطوتك، عليك إعداد عملية نشر تجريبية للإضافة، وإضافة الخطوة إلى مسار، ثم تشغيل المسار.

  1. إعداد عملية نشر تجريبية للإضافة:

    1. افتح مشروع البرنامج النصي في محرّر Apps Script.
    2. انقر على نشر > اختبار عمليات النشر.
    3. انقر على تثبيت.
    4. في أسفل الصفحة، انقر على تم.

    يمكنك السماح لمستخدمين آخرين باختبار الإضافة من خلال مشاركة مشروع Apps Script مع حساباتهم (يجب منحهم إذن التعديل). بعد ذلك، اطلب من المستخدمين اتّباع الخطوات السابقة.

    بعد تثبيت الوظيفة الإضافية، ستتوفّر على الفور في "سير العمل". قد تحتاج إلى إعادة تحميل Flows قبل ظهور الإضافة. يجب أيضًا تفويض الإضافة قبل استخدامها.

    لمزيد من المعلومات عن عمليات النشر التجريبية، اطّلِع على تثبيت إضافة غير منشورة.

  2. فتح "المخططات"

  3. أنشئ تدفقًا يتضمّن خطوتك:

    1. انقر على تدفق جديد.
    2. اختَر طريقة بدء المسار. عند اختبار خطوة، من المستحسن اختيار بداية يمكنك إعدادها بنفسك، مثل إرسال رسالة إلكترونية إلى نفسك. إذا كانت خطوتك تتطلّب متغيّر إدخال، اضبط متغيّر الإدخال كجزء من ناتج المشغّل.
    3. انقر على إضافة خطوة. اختَر الخطوة التي أنشأتها أو عدّلتها، والتي تُسمى الحساب.
    4. اضبط خطوتك. بالنسبة إلى خطوة الحساب، اختَر قيمتَين وعملية حسابية. يتم حفظ الخطوة تلقائيًا.
    5. لاختبار ناتج الخطوة، أضِف خطوة أخرى. على سبيل المثال، لإضافة ناتج إلى رسالة إلكترونية، يمكنك إضافة خطوة إرسال رسالة في Gmail. في الرسالة، انقر على المتغيرات واختَر ناتج الخطوة. بالنسبة إلى خطوة "الحساب"، اختَر المتغيرات > الخطوة 2: النتيجة المحسوبة > النتيجة المحسوبة. يظهر المتغيّر على شكل شريحة في حقل الرسالة.
    6. انقروا على تفعيل. أصبح التدفق جاهزًا للتنفيذ.

  4. شغِّل السلسلة من خلال تفعيل إجراء التفعيل. على سبيل المثال، إذا كان مسارك يبدأ عند تلقّي رسالة إلكترونية، أرسِل رسالة إلكترونية إلى نفسك.

  5. تأكَّد من أنّ المسار يعمل على النحو المتوقّع. يمكنك الاطّلاع على السجلات من خلال الانتقال إلى علامة التبويب النشاط في "أداة إنشاء سير العمل". لمعرفة كيفية إنشاء سجلّات مخصّصة في علامة التبويب "النشاط"، اطّلِع على سجلّات الأنشطة.