機能のベストプラクティス

テーブルへの書き込みには Functions を使用してください

推奨されるアプローチ

複数のアプリやアプリステップが同じテーブルに書き込みを行う場合、および以下を強制する必要がある場合に、関数を作成してください：

• 必須フィールド
• 有効な値（例：ステータスは承認済みリストに含まれる値に限る）
• 一貫性のあるメタデータ（作成者、作成日時）

これが重要な理由

市民開発者がトリガー内で直接テーブルレコードを作成する場合、次のような問題が生じる可能性があります：

• IDの命名規則に従わない
• 必須フィールドの入力漏れ
• フィールド値のスペルミス（「in progress」と「in-progress」など）
• メタデータの入力に一貫性がない

関数を使用すれば、同一のスキーマを強制し、こうしたエラーを防ぐことができます。

例

各アプリ開発者が、フィールドや内容が不統一な「サンプル」レコードを作成することを許すのではなく、次のような「サンプル作成」関数を作成します。

• 一貫性のある入力（ジョブID、サンプルタイプ、数量、タイムスタンプ、ユーザー、アプリ名）を必須とする
• サンプルタイプが承認済みリストに含まれていることを検証する

関数：CreateSample 入力： - job_id (テキスト) - sample_type (テキスト) - quantity (数値) - app name (テキスト) - user requesting (ユーザー)

ロジック：1. sample_type が ["A", "B", "C"] に含まれていることを検証する 2. 無効な場合は、エラーメッセージを返す 3. 以下の内容でテーブルレコードを作成する： - ID：関数内で生成 - ジョブ ID：入力値 - サンプルタイプ：入力値 - 数量：入力値 - ロット番号：入力値（指定されていない場合は空） - 作成者：入力値4. 成功メッセージを返す

出力： - ステータス（テキスト）：「success」または「error」 - メッセージ（テキスト）：失敗した場合のエラー説明

サンプルのテーブルレコードを作成する必要がある場合は、入力を関数に渡せば、残りの処理は関数が自動的に行います。

避けるべきパターン

単純な操作であっても、テーブルへの書き込み操作ごとに関数を作成しないでください。

これが問題を引き起こす理由

• 関数が乱立する（数百もの単発関数が作られる）
• 単純な書き込みに対して、メリットのない複雑さを増す
• デバッグが困難になる（確認すべき箇所が増える）

テーブルへの書き込みで関数の使用を避けるべき場合

• 既存のテーブルレコードを更新する場合（例：ステータスの更新や数量の減算）
• 単一のアプリによるテーブルへの書き込み
• ガバナンスや検証が不要な場合

反復的な多段階ロジックには関数を使用する

推奨されるアプローチ

複数のアプリにまたがる多くのステップで、同じ一連のトリガーアクションが発生する場合は、それを関数として抽出します。

例：ラベル印刷用のZPLコードを取得する

関数：ZPLコードの取得入力： - 材料ID（テキスト）

変数： - ZPLコード変数（テキスト）

出力： - ZPLコード（テキスト）

ロジック：1. データの更新：構成「ZPLコード変数」 - 設定値：[@Inputs.Material ID を含む ZPLコードの式]2. 返却：'ZPLコード' データソース「ZPLコード変数」

避けるべきパターン

すべてのアプリを通じて合計で1～2回しか発生しないロジックのための関数は作成しないでください。

これが問題を引き起こす理由

• 関数の管理にかかるオーバーヘッドが、得られるメリットを上回る
• アプリ開発者が、ごく稀なケースのために関数のインターフェースを習得せざるを得なくなる
• 関数とアプリの間を行き来する必要があるため、デバッグが困難になる

コネクタ関数を関数内に埋め込む

推奨されるアプローチ

コネクタ関数を使用する際は、そのコネクタ関数の入力引数を、コネクタ関数を呼び出す関数に渡してください。そうすることで、その関数内でタイムアウト時の再試行やエラー処理をより簡単かつ一元的に処理できるようになり、ソリューション全体のアプリロジックを簡素化できます。

また、コネクタ関数を関数内に組み込むことで、個々のアプリに加える必要のある変更量を減らすことができ、将来的なERP移行の際の負担を最小限に抑えることができます。

例

関数: Update ProcessOrder入力: - 注文ID (テキスト) - ステータス (テキスト)

出力： - エラーメッセージ (テキスト)

変数： - HTTPコード（整数） - タイムアウト再試行回数（整数） - エラーメッセージ（テキスト）

ロジック：1. コネクタ関数を実行する 2. HTTP コードが成功の場合、関数を終了する 3. HTTP コードがタイムアウトであり、「タイムアウト再試行回数」が指定値以下である場合は、「タイムアウト再試行回数」をインクリメントし、「コネクタ関数の実行」に戻る4. HTTP コードが関数のロジックでは解決できないコードである場合は、「エラーメッセージ」出力に役立つメッセージを返す

個々のテーブルレコードフィールドではなく、レコード ID を渡す

推奨されるアプローチ

関数でテーブルレコードのデータが必要な場合は、レコード ID を渡し、関数内でそのレコードを読み込んでください。

例

次の例は論理的には正しいですが（「Order ID」は Orders テーブルの ID であり、他のフィールドはそのテーブルの列です）、「Order ID」は Orders テーブルの ID であり、他のフィールドはそのテーブルの列です）、よりシンプルな設定があります。

関数：注文処理入力： - 注文ID（テキスト） - 顧客名（テキスト） - 製品ID（テキスト） - 数量（数値） - 納期（日時） - 優先度（テキスト）

ロジック：1. [入力フィールドを使用してロジックを実行]

以下の例では、最小限の入力で同じ結果を実現しています：

関数：注文処理入力項目： - 注文ID（テキスト）

ロジック：1. テーブルレコードを取得：ID = 「注文ID」入力のOrdersテーブル2. [テーブルレコードのフィールドを使用してロジックを実行]

2番目の例の方が優れたアプローチである理由：

• 入力項目が少ない（6つ以上ではなく1つ）
• テーブルのスキーマが変更されても、関数を容易に適応させることができる
• アプリ内での関数呼び出しがすっきりする
• 誤ったフィールドを誤った入力にマッピングしてしまう可能性が低減される

関数と引数の名前付けおよび説明を統一する

推奨されるアプローチ

ワークスペース内のすべての関数で、一貫した命名規則を使用してください。

関数名

• 動詞＋名詞の形式を使用する：「Create Sample」、「Update Job Status」、「Validate Serial Number」など
• 名詞のみの使用は避けてください：「Sample」、「Job」、「Serial Number」

関数の説明

• 関数の動作について、直感的に理解できる説明を記述してください。たとえば、「Create Defect」という名前の関数については、「Defects テーブルに、ステータスが OPEN の新しいレコードを作成する」といった説明を記述してください。

入力項目の名称

• 用語は統一してください：常に「Work Order ID」を使用し（「Order ID」や「Work_id」を混在させないでください）
• 可能な場合は、テーブルのフィールド名と一致させてください

ロジックブロックの名前

• 明確に記述してください：「Get Table Record」ではなく「Get Job Record」
• 将来の読者のために：「サンプルタイプの検証」とし、「値の確認」とはしない

これが重要な理由

• アプリ開発者は関数の目的をすぐに理解できる
• 複数の関数を使用する際の認知的負荷を軽減する
• 「使用箇所」の分析が容易になる
• ドキュメントやトレーニングの質が向上する

入力の妥当性チェックとユーザー向けエラーメッセージをシームレスに処理

推奨されるアプローチ

関数の引数は常に必須項目として指定し、必要に応じて入力検証ルールを使用してください。関数内での入力の検証は行わないでください。

これが重要な理由

• アプリユーザーは値を入力する際に明確なフィードバックを得られる
• アプリの側で入力の妥当性チェックを行い、関数には確実に有効な入力のみを渡すことで、関数のロジックを簡素化できる
• 不正な入力によるデータの破損を防ぐ

避けるべきパターン

関数内で入力の検証を行わないでください。

これが問題を引き起こす理由

• アプリエディタで利用できる入力検証機能と重複してしまう
• 関数内で入力の妥当性を再確認することによる、不必要な追加の遅延が生じる

ループ内でのテーブルクエリを最小限に抑える

関数で配列をループ処理する場合、各反復ごとにテーブルをクエリしないようにしてください。代わりに、ループの前に一度クエリを実行し、その結果を参照するようにしてください。

ロジックには関数を使用し、単純な参照には使用しない

単一のテーブルレコードを取得するだけの関数は作成しないでください。それにはrecord placeholders を使用してください。関数は、データを変換するロジックのために留保してください。

出力サイズを制限する

関数が大きなオブジェクトや配列を返す場合は、オブジェクト配列全体ではなく、アプリに必要なフィールドのみを返すことを検討してください。

追加リソース