#नोड प्रकारों का विस्तार करना

एक नोड का प्रकार मूल रूप से एक ऑपरेशनल निर्देश होता है। अलग-अलग निर्देश वर्कफ़्लो में किए जाने वाले अलग-अलग ऑपरेशंस को दर्शाते हैं।

ट्रिगर की तरह ही, नोड प्रकारों का विस्तार भी दो भागों में बंटा हुआ है: सर्वर-साइड और क्लाइंट-साइड। सर्वर-साइड को पंजीकृत निर्देश के लिए लॉजिक लागू करना होता है, जबकि क्लाइंट-साइड को उस नोड के पैरामीटर्स के लिए इंटरफ़ेस कॉन्फ़िगरेशन प्रदान करना होता है जहाँ निर्देश स्थित है।

#सर्वर-साइड

#सबसे सरल नोड निर्देश

एक निर्देश का मुख्य भाग एक फ़ंक्शन होता है, जिसका अर्थ है कि निर्देश क्लास में run मेथड को निर्देश के लॉजिक को निष्पादित करने के लिए लागू करना अनिवार्य है। फ़ंक्शन के भीतर कोई भी आवश्यक ऑपरेशन किए जा सकते हैं, जैसे कि डेटाबेस ऑपरेशन, फ़ाइल ऑपरेशन, थर्ड-पार्टी API को कॉल करना आदि।

सभी निर्देशों को Instruction बेस क्लास से व्युत्पन्न (derived) होना चाहिए। सबसे सरल निर्देश को केवल एक run फ़ंक्शन को लागू करने की आवश्यकता होती है:

import { Instruction, JOB_STATUS } from '@nocobase/plugin-workflow';

export class MyInstruction extends Instruction {
  run(node, input, processor) {
    console.log('my instruction runs!');
    return {
      status: JOB_STATUS.RESOVLED,
    };
  }
}

और इस निर्देश को वर्कफ़्लो प्लगइन में पंजीकृत करें:

export default class MyPlugin extends Plugin {
  load() {
    // get workflow plugin instance
    const workflowPlugin = this.app.getPlugin<WorkflowPlugin>(WorkflowPlugin);

    // register instruction
    workflowPlugin.registerInstruction('my-instruction', MyInstruction);
  }
}

निर्देश के रिटर्न ऑब्जेक्ट में स्टेटस वैल्यू (status) अनिवार्य है और यह JOB_STATUS कॉन्स्टेंट से एक वैल्यू होनी चाहिए। यह वैल्यू वर्कफ़्लो में इस नोड के लिए बाद की प्रोसेसिंग के प्रवाह को निर्धारित करती है। आमतौर पर, JOB_STATUS.RESOVLED का उपयोग किया जाता है, जो दर्शाता है कि नोड सफलतापूर्वक निष्पादित हो गया है और निष्पादन अगले नोड्स तक जारी रहेगा। यदि कोई परिणाम वैल्यू है जिसे पहले से सहेजने की आवश्यकता है, तो आप processor.saveJob मेथड को भी कॉल कर सकते हैं और उसका रिटर्न ऑब्जेक्ट वापस कर सकते हैं। एक्ज़ीक्यूटर इस ऑब्जेक्ट के आधार पर एक निष्पादन परिणाम रिकॉर्ड उत्पन्न करेगा।

#नोड परिणाम वैल्यू

यदि कोई विशिष्ट निष्पादन परिणाम है, खासकर बाद के नोड्स द्वारा उपयोग के लिए तैयार किया गया डेटा, तो इसे result प्रॉपर्टी के माध्यम से वापस किया जा सकता है और नोड के जॉब ऑब्जेक्ट में सहेजा जा सकता है:

import { Instruction, JOB_STATUS } from '@nocobase/plugin-workflow';

export class RandomStringInstruction extends Instruction {
  run(node, input, processor) {
    // customized config from node
    const { digit = 1 } = node.config;
    const result = `${Math.round(10 ** digit * Math.random())}`.padStart(
      digit,
      '0',
    );
    return {
      status: JOB_STATUS.RESOVLED,
      result,
    };
  },
};

यहाँ, node.config नोड का कॉन्फ़िगरेशन आइटम है, जो कोई भी आवश्यक वैल्यू हो सकता है। इसे डेटाबेस में संबंधित नोड रिकॉर्ड में JSON प्रकार के फ़ील्ड के रूप में सहेजा जाएगा।

#निर्देश त्रुटि प्रबंधन

यदि निष्पादन के दौरान अपवाद (exceptions) हो सकते हैं, तो आप उन्हें पहले से पकड़ सकते हैं और विफल स्थिति वापस कर सकते हैं:

import { JOB_STATUS } from '@nocobase/plugin-workflow';

export const errorInstruction = {
  run(node, input, processor) {
    try {
      throw new Error('exception');
    } catch (error) {
      return {
        status: JOB_STATUS.ERROR,
        result: error,
      };
    }
  },
};

यदि अनुमानित अपवादों को नहीं पकड़ा जाता है, तो वर्कफ़्लो इंजन उन्हें स्वचालित रूप से पकड़ लेगा और एक त्रुटि स्थिति वापस कर देगा, ताकि अनकैच किए गए अपवादों से प्रोग्राम क्रैश होने से बचा जा सके।

#एसिंक्रोनस नोड्स

जब फ़्लो कंट्रोल या एसिंक्रोनस (समय लेने वाले) I/O ऑपरेशंस की आवश्यकता होती है, तो run मेथड JOB_STATUS.PENDING स्टेटस के साथ एक ऑब्जेक्ट वापस कर सकता है, जो एक्ज़ीक्यूटर को प्रतीक्षा (निलंबित) करने के लिए प्रेरित करता है जब तक कि कुछ बाहरी एसिंक्रोनस ऑपरेशन पूरा न हो जाए, और फिर वर्कफ़्लो इंजन को निष्पादन जारी रखने के लिए सूचित करता है। यदि run फ़ंक्शन में लंबित स्टेटस वैल्यू वापस की जाती है, तो निर्देश को resume मेथड को लागू करना होगा; अन्यथा, वर्कफ़्लो का निष्पादन फिर से शुरू नहीं किया जा सकता है:

import { Instruction, JOB_STATUS } from '@nocobase/plugin-workflow';

export class PayInstruction extends Instruction {
  async run(node, input, processor) {
    // job could be create first via processor
    const job = await processor.saveJob({
      status: JOB_STATUS.PENDING,
    });

    const { workflow } = processor;
    // do payment asynchronously
    paymentService.pay(node.config, (result) => {
      // notify processor to resume the job
      return workflow.resume(job.id, result);
    });

    // return created job instance
    return job;
  }

  resume(node, job, processor) {
    // check payment status
    job.set('status', job.result.status === 'ok' ? JOB_STATUS.RESOVLED : JOB_STATUS.REJECTED);
    return job;
  },
};

यहाँ, paymentService एक भुगतान सेवा को संदर्भित करता है। सेवा के कॉलबैक में, वर्कफ़्लो को संबंधित जॉब के निष्पादन को फिर से शुरू करने के लिए ट्रिगर किया जाता है, और वर्तमान प्रक्रिया पहले बाहर निकल जाती है। बाद में, वर्कफ़्लो इंजन एक नया प्रोसेसर बनाता है और उसे नोड के resume मेथड में भेजता है ताकि पहले निलंबित किए गए नोड को निष्पादित करना जारी रखा जा सके।

#नोड परिणाम स्थिति

एक नोड की निष्पादन स्थिति पूरे वर्कफ़्लो की सफलता या विफलता को प्रभावित करती है। आमतौर पर, शाखाओं के बिना, किसी नोड की विफलता सीधे पूरे वर्कफ़्लो की विफलता का कारण बनती है। सबसे सामान्य परिदृश्य यह है कि यदि कोई नोड सफलतापूर्वक निष्पादित होता है, तो वह नोड तालिका में अगले नोड पर आगे बढ़ता है जब तक कि कोई और नोड न हो, जिस बिंदु पर पूरा वर्कफ़्लो एक सफल स्थिति के साथ पूरा हो जाता है।

यदि निष्पादन के दौरान कोई नोड विफल निष्पादन स्थिति वापस करता है, तो इंजन निम्नलिखित दो स्थितियों के आधार पर इसे अलग तरह से संभालेगा:

1. विफल स्थिति वापस करने वाला नोड मुख्य वर्कफ़्लो में है, जिसका अर्थ है कि यह किसी भी अपस्ट्रीम नोड द्वारा खोले गए किसी भी शाखा वर्कफ़्लो के भीतर नहीं है। इस स्थिति में, पूरे मुख्य वर्कफ़्लो को विफल माना जाएगा, और प्रक्रिया बाहर निकल जाएगी।

2. विफल स्थिति वापस करने वाला नोड किसी शाखा वर्कफ़्लो के भीतर है। इस स्थिति में, वर्कफ़्लो की अगली स्थिति निर्धारित करने की जिम्मेदारी उस नोड को सौंप दी जाती है जिसने शाखा खोली थी। उस नोड का आंतरिक लॉजिक बाद के वर्कफ़्लो की स्थिति तय करेगा, और यह निर्णय मुख्य वर्कफ़्लो तक पुनरावर्ती रूप से प्रसारित होगा।

अंततः, पूरे वर्कफ़्लो की अगली स्थिति मुख्य वर्कफ़्लो के नोड्स पर निर्धारित की जाती है। यदि मुख्य वर्कफ़्लो में कोई नोड विफलता वापस करता है, तो पूरा वर्कफ़्लो विफल स्थिति के साथ समाप्त होता है।

यदि कोई नोड निष्पादन के बाद "लंबित" स्थिति वापस करता है, तो पूरी निष्पादन प्रक्रिया को अस्थायी रूप से बाधित और निलंबित कर दिया जाएगा, जो वर्कफ़्लो के निष्पादन को फिर से शुरू करने के लिए संबंधित नोड द्वारा परिभाषित एक इवेंट के ट्रिगर होने की प्रतीक्षा करेगा। उदाहरण के लिए, मैनुअल नोड, जब निष्पादित होता है, तो "लंबित" स्थिति के साथ उस नोड पर रुक जाएगा, मैन्युअल हस्तक्षेप की प्रतीक्षा करेगा ताकि यह तय किया जा सके कि पास करना है या नहीं। यदि मैन्युअल रूप से दर्ज की गई स्थिति पास है, तो बाद के वर्कफ़्लो नोड्स जारी रहेंगे; अन्यथा, इसे पहले वर्णित विफलता लॉजिक के अनुसार संभाला जाएगा।

अधिक निर्देश रिटर्न स्टेटस के लिए, कृपया वर्कफ़्लो API संदर्भ अनुभाग देखें।

#शीघ्र बाहर निकलना

कुछ विशेष वर्कफ़्लो में, किसी नोड के भीतर सीधे वर्कफ़्लो को समाप्त करना आवश्यक हो सकता है। आप null वापस कर सकते हैं, जो वर्तमान वर्कफ़्लो से बाहर निकलने का संकेत देता है, और बाद के नोड्स निष्पादित नहीं होंगे।

यह स्थिति कुछ फ़्लो कंट्रोल प्रकार के नोड्स में आम है, जैसे कि पैरेलल ब्रांच नोड में (कोड संदर्भ), जहाँ वर्तमान नोड का वर्कफ़्लो बाहर निकल जाता है, लेकिन प्रत्येक उप-शाखा के लिए नए वर्कफ़्लो शुरू किए जाते हैं और निष्पादन जारी रहता है।

:::warn{title=चेतावनी} विस्तारित नोड्स के साथ शाखा वर्कफ़्लो को शेड्यूल करने में कुछ जटिलता होती है, और इसके लिए सावधानीपूर्वक प्रबंधन और गहन परीक्षण की आवश्यकता होती है। :::

#और जानें

नोड प्रकारों को परिभाषित करने के लिए विभिन्न पैरामीटर्स की परिभाषाएँ वर्कफ़्लो API संदर्भ अनुभाग में देखें।

#क्लाइंट-साइड

ट्रिगर की तरह ही, एक निर्देश (नोड प्रकार) के लिए कॉन्फ़िगरेशन फ़ॉर्म को क्लाइंट-साइड पर लागू करने की आवश्यकता होती है।

#सबसे सरल नोड निर्देश

सभी निर्देशों को Instruction बेस क्लास से व्युत्पन्न (derived) होना चाहिए। संबंधित प्रॉपर्टीज़ और मेथड्स का उपयोग नोड को कॉन्फ़िगर करने और उपयोग करने के लिए किया जाता है।

उदाहरण के लिए, यदि हमें ऊपर सर्वर-साइड पर परिभाषित रैंडम नंबर स्ट्रिंग प्रकार (randomString) के नोड के लिए एक कॉन्फ़िगरेशन इंटरफ़ेस प्रदान करने की आवश्यकता है, जिसमें एक कॉन्फ़िगरेशन आइटम digit है जो रैंडम नंबर के अंकों की संख्या को दर्शाता है, तो हम उपयोगकर्ता इनपुट प्राप्त करने के लिए कॉन्फ़िगरेशन फ़ॉर्म में एक संख्या इनपुट बॉक्स का उपयोग करेंगे।

import WorkflowPlugin, { Instruction, VariableOption } from '@nocobase/workflow/client';

class MyInstruction extends Instruction {
  title = 'Random number string';
  type = 'randomString';
  group = 'extended';
  fieldset = {
    'digit': {
      type: 'number',
      title: 'Digit',
      name: 'digit',
      'x-decorator': 'FormItem',
      'x-component': 'InputNumber',
      'x-component-props': {
        min: 1,
        max: 10,
      },
      default: 6,
    },
  };
  useVariables(node, options): VariableOption {
    return {
      value: node.key,
      label: node.title,
    };
  }
}

export default class MyPlugin extends Plugin {
  load() {
    // get workflow plugin instance
    const workflowPlugin = this.app.getPlugin<WorkflowPlugin>(WorkflowPlugin);

    // register instruction
    workflowPlugin.registerInstruction('log', LogInstruction);
  }
}

#नोड परिणामों को वेरिएबल के रूप में प्रदान करना

आप ऊपर दिए गए उदाहरण में useVariables मेथड पर ध्यान दे सकते हैं। यदि आपको नोड के परिणाम (result भाग) को बाद के नोड्स द्वारा उपयोग के लिए एक वेरिएबल के रूप में उपयोग करने की आवश्यकता है, तो आपको इनहेरिटेड निर्देश क्लास में इस मेथड को लागू करना होगा और VariableOption प्रकार के अनुरूप एक ऑब्जेक्ट वापस करना होगा। यह ऑब्जेक्ट नोड के निष्पादन परिणाम के संरचनात्मक विवरण के रूप में कार्य करता है, जो बाद के नोड्स में चयन और उपयोग के लिए वेरिएबल नाम मैपिंग प्रदान करता है।

यहाँ VariableOption प्रकार की परिभाषा इस प्रकार है:

export type VariableOption = {
  value?: string;
  label?: string;
  children?: VariableOption[] | null;
  [key: string]: any;
};

मुख्य value प्रॉपर्टी है, जो वेरिएबल नाम के खंडित पथ मान को दर्शाती है। label का उपयोग इंटरफ़ेस पर प्रदर्शित करने के लिए किया जाता है, और children का उपयोग बहु-स्तरीय वेरिएबल संरचना को दर्शाने के लिए किया जाता है, जिसका उपयोग तब किया जाता है जब नोड का परिणाम एक गहरा नेस्टेड ऑब्जेक्ट होता है।

सिस्टम के भीतर एक उपयोग योग्य वेरिएबल को . से अलग किए गए पथ टेम्पलेट स्ट्रिंग के रूप में दर्शाया जाता है, उदाहरण के लिए, {{jobsMapByNodeKey.2dw92cdf.abc}}। यहाँ, jobsMapByNodeKey सभी नोड्स के परिणाम सेट को दर्शाता है (आंतरिक रूप से परिभाषित, संभालने की आवश्यकता नहीं), 2dw92cdf नोड की key है, और abc नोड के परिणाम ऑब्जेक्ट में एक कस्टम प्रॉपर्टी है।

इसके अतिरिक्त, चूंकि एक नोड का परिणाम एक साधारण वैल्यू भी हो सकता है, इसलिए नोड वेरिएबल प्रदान करते समय, पहली लेयर नोड का स्वयं का विवरण होनी चाहिए:

{
  value: node.key,
  label: node.title,
}

अर्थात, पहली लेयर नोड की key और शीर्षक है। उदाहरण के लिए, कैलकुलेशन नोड के कोड संदर्भ में, कैलकुलेशन नोड के परिणाम का उपयोग करते समय, इंटरफ़ेस विकल्प इस प्रकार हैं:

जब नोड का परिणाम एक जटिल ऑब्जेक्ट होता है, तो आप children का उपयोग करके गहरी नेस्टेड प्रॉपर्टीज़ का वर्णन करना जारी रख सकते हैं। उदाहरण के लिए, एक कस्टम निर्देश निम्नलिखित JSON डेटा वापस कर सकता है:

{
  "message": "ok",
  "data": {
    "id": 1,
    "name": "test",
  }
}

तो आप इसे useVariables मेथड के माध्यम से इस प्रकार वापस कर सकते हैं:

useVariables(node, options): VariableOption {
  return {
    value: node.key,
    label: node.title,
    children: [
      {
        value: 'message',
        label: 'Message',
      },
      {
        value: 'data',
        label: 'Data',
        children: [
          {
            value: 'id',
            label: 'ID',
          },
          {
            value: 'name',
            label: 'Name',
          },
        ],
      },
    ],
  };
}

इस तरह, बाद के नोड्स में, आप इसमें से वेरिएबल चुनने के लिए निम्नलिखित इंटरफ़ेस का उपयोग कर सकते हैं:

#नोड की उपलब्धता

डिफ़ॉल्ट रूप से, वर्कफ़्लो में कोई भी नोड जोड़ा जा सकता है। हालाँकि, कुछ स्थितियों में, एक नोड कुछ विशिष्ट प्रकार के वर्कफ़्लो या शाखाओं में लागू नहीं हो सकता है। ऐसी स्थितियों में, आप isAvailable का उपयोग करके नोड की उपलब्धता को कॉन्फ़िगर कर सकते हैं:

// Type definition
export abstract class Instruction {
  isAvailable?(ctx: NodeAvailableContext): boolean;
}

export type NodeAvailableContext = {
  // Workflow plugin instance
  engine: WorkflowPlugin;
  // Workflow instance
  workflow: object;
  // Upstream node
  upstream: object;
  // Whether it is a branch node (branch number)
  branchIndex: number;
};

जब isAvailable मेथड true वापस करता है तो इसका मतलब है कि नोड उपलब्ध है, और false का मतलब है कि यह उपलब्ध नहीं है। ctx पैरामीटर में वर्तमान नोड की कॉन्टेक्स्ट जानकारी शामिल होती है, जिसका उपयोग यह निर्धारित करने के लिए किया जा सकता है कि नोड उपलब्ध है या नहीं।

यदि कोई विशेष आवश्यकताएँ नहीं हैं, तो आपको isAvailable मेथड को लागू करने की आवश्यकता नहीं है, क्योंकि नोड्स डिफ़ॉल्ट रूप से उपलब्ध होते हैं। कॉन्फ़िगरेशन की सबसे सामान्य आवश्यकता तब होती है जब कोई नोड एक समय लेने वाला ऑपरेशन हो सकता है और सिंक्रोनस वर्कफ़्लो में निष्पादन के लिए उपयुक्त नहीं होता है। आप isAvailable मेथड का उपयोग करके नोड के उपयोग को प्रतिबंधित कर सकते हैं। उदाहरण के लिए:

isAvailable({ engine, workflow, upstream, branchIndex }) {
  return !engine.isWorkflowSync(workflow);
}

#और जानें

नोड प्रकारों को परिभाषित करने के लिए विभिन्न पैरामीटर्स की परिभाषाएँ वर्कफ़्लो API संदर्भ अनुभाग में देखें।