開発中の機能
コード管理
SDK
defineAction

defineAction

アクションを定義する関数です。classフィールドで種別を指定し、種別に応じたフィールドを設定します。

classによって設定できるフィールドが型で絞り込まれるため、存在しないフィールドを指定するとTypeScriptのコンパイルエラーになります。

以下の設定項目はコード管理の対象外です。これらはベースマキナの管理画面から設定してください。

  • 結果の加工(加工スクリプト、ページネーション)
  • 環境ごとの有効/無効
  • 環境ごとのバージョン

共通フィールド

すべてのアクション種別で使用できるフィールドです。

フィールド必須説明
idstringはいアクションの識別子。1〜128文字で、使用できる文字は英数字・アンダースコア・ハイフン(^[a-zA-Z0-9_-]+$
namestringはいアクション名。1〜128文字
descriptionstringいいえ説明。最大1000文字
preferJobExecutionbooleanいいえジョブ実行を優先的に表示するか
jobDetailVisibility"EXECUTOR_ONLY" | "PUBLIC"いいえジョブ詳細の公開範囲
reviewSettingIdstringいいえレビュー設定の識別子
notificationSettingsNotificationSettingsConfigいいえ通知設定
permissions[PermissionTarget, ...](非空)いいえ実行権限の対象。指定する場合は1件以上必要

permissions

permissionsは実行を許可する対象の配列です。指定しない場合はプロジェクト内の全ユーザーに実行が許可されます。

permissions: [
  { type: "user", id: "<ユーザーID>" },
  { type: "userGroup", id: "<ユーザーグループID>" },
  { type: "javascriptAction", id: "<JavaScriptアクションの識別子>" },
];
type説明
"user"特定のユーザーに実行を許可
"userGroup"特定のユーザーグループに属するユーザーに実行を許可
"javascriptAction"JavaScriptアクションの判定結果に従って実行を許可

notificationSettings

アクションの成功時・失敗時に通知するための設定です。

notificationSettings: {
  onSuccess: {
    notificationMethodId: "<通知方法の識別子>",
    mentionTargetUserIds: ["<ユーザーID>"],
    message: "ユーザー作成が成功しました",
  },
  onError: {
    notificationMethodId: "<通知方法の識別子>",
    message: "ユーザー作成に失敗しました",
  },
};
フィールド必須説明
onSuccess.notificationMethodIdstringはい通知方法の識別子
onSuccess.mentionTargetUserIdsstring[]いいえメンション対象ユーザー
onSuccess.messagestringいいえ通知メッセージ
onError.notificationMethodIdstringはい通知方法の識別子
onError.mentionTargetUserIdsstring[]いいえメンション対象ユーザー
onError.messagestringいいえ通知メッセージ

onSuccessonErrorはどちらも省略可能で、必要な方だけ指定できます。

gRPCアクション

import { defineAction } from "@basemachina/sdk/oac";
 
export const fetchOrders = defineAction({
  id: "fetch-orders",
  name: "注文一覧取得",
  class: "grpc",
  dataSource: "orders-service",
  fullyQualifiedMethodName: "orders.OrderService/ListOrders",
  parameters: [{ type: "TEXT", name: "customerId", required: true }],
});
フィールド必須説明
class"grpc"はいgRPCアクションを指定
dataSourcestringはいデータソースの識別子
fullyQualifiedMethodNamestringはいgRPCメソッドの完全修飾名
headers{ name: string; value: string }[]いいえリクエストヘッダー
body{ payload: string }いいえリクエストボディ
parametersParameterConfig[]いいえパラメーター定義(下記参照)

JavaScriptアクション

import { defineAction, readFile } from "@basemachina/sdk/oac";
 
export const createUser = defineAction({
  id: "create-user",
  name: "ユーザー作成",
  class: "javascript",
  code: readFile("./js-action-codes/create-user.ts"),
  parameters: [
    { type: "TEXT", name: "email", required: true },
    { type: "NUMBER", name: "age", required: true },
  ],
});
フィールド必須説明
class"javascript"はいJavaScriptアクションを指定
codestringはいJavaScriptコードまたはreadFile()の戻り値
parametersParameterConfig[]いいえパラメーター定義(下記参照)

パラメーター定義

parametersには、アクションの入力パラメーターをtypeフィールドで種別を分けて配列で指定します。gRPCアクションとJavaScriptアクションで、使用できるパラメーター種別とformatTypeが一部異なります。

すべての種別に共通で、nameは1〜128文字、descriptionは最大400文字までです。

パラメーター種別gRPCJavaScript
TEXT使用可使用可
NUMBER使用可使用可
DATE使用可使用可
BOOL使用可使用可
SYSTEM_VALUE使用可使用可
JSON使用可使用不可
FILE使用不可使用可
ARRAY使用可使用可
TUPLE使用可使用可

TEXTパラメーター

{
  type: "TEXT",
  name: "email",
  required: true,
  defaultValue: "example@example.com",
  minLength: 1,
  maxLength: 255,
  multiline: false,
  regexValidation: "^[\\w.+-]+@[\\w-]+\\.[\\w.]+$",
  regexErrorMessage: "メールアドレスの形式で入力してください",
}
フィールド必須説明
type"TEXT"はいテキストパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
defaultValuestringいいえデフォルト値
minLengthnumberいいえ最小文字数
maxLengthnumberいいえ最大文字数
multilinebooleanいいえ複数行入力を許可するか
newlineCharactersstringいいえmultiline: trueの場合の改行コード
regexValidationstringいいえ入力値のバリデーション正規表現(multiline: falseのみ)
regexErrorMessagestringいいえバリデーションエラー時のメッセージ
selectOptions{ label: string; value: string }[]いいえ選択肢(multiline: falseのみ)
masterDataFetchSettingIdstringいいえマスターデータ取得設定の識別子(multiline: falseのみ)

selectOptionsmasterDataFetchSettingIdは排他関係にあり、どちらか一方のみ指定できます。

NUMBERパラメーター

{
  type: "NUMBER",
  name: "age",
  required: true,
  min: 0,
  max: 150,
}
フィールド必須説明
type"NUMBER"はい数値パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
defaultValuenumberいいえデフォルト値
minnumberいいえ最小値
maxnumberいいえ最大値
selectOptions{ label: string; value: number }[]いいえ選択肢
masterDataFetchSettingIdstringいいえマスターデータ取得設定の識別子

DATEパラメーター

// ISO文字列で扱う場合
{
  type: "DATE",
  name: "targetDate",
  required: true,
  includeTime: false,
  format: "YYYY-MM-DD",
  defaultValue: "2025-01-01",
}
 
// Unixタイムスタンプで扱う場合
{
  type: "DATE",
  name: "targetDate",
  required: true,
  includeTime: true,
  useUnixTimestamp: true,
  defaultValue: 1735689600,
}
フィールド必須説明
type"DATE"はい日付パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
includeTimebooleanいいえ時刻を含めるか
useUnixTimestampbooleanいいえUnixタイムスタンプで扱うか。trueの場合formatは指定不可
formatstringいいえ日付フォーマット(useUnixTimestamp: falseの場合のみ)
defaultValuestring | numberいいえデフォルト値(useUnixTimestamp: trueの場合はnumber

BOOLパラメーター

// JavaScriptアクションの例(真偽値で扱う)
{
  type: "BOOL",
  name: "isActive",
  formatType: "RAW",
  defaultValue: true,
}
 
// JavaScriptアクションの例(文字列で扱う)
{
  type: "BOOL",
  name: "isActive",
  formatType: "STRING",
  trueValue: "1",
  falseValue: "0",
}
 
// gRPCアクションの例(BOOLは文字列形式のみ、formatType指定不要)
{
  type: "BOOL",
  name: "isActive",
  trueValue: "true",
  falseValue: "false",
}
フィールド必須説明
type"BOOL"はい真偽値パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
defaultValuebooleanいいえデフォルト値
formatType"RAW" | "STRING"JavaScriptで必須、gRPCでは不要値の扱い方。"RAW"は真偽値、"STRING"trueValue/falseValueの文字列
trueValuestringformatType: "STRING"で必須trueのときに送信する文字列
falseValuestringformatType: "STRING"で必須falseのときに送信する文字列

gRPCアクションのBOOLは常に文字列形式で扱われるため、formatTypeの指定は不要でtrueValue/falseValueが必須です。

FILEパラメーター(JavaScriptアクションのみ)

{
  type: "FILE",
  name: "uploadFile",
  required: true,
  maxBytes: 10485760,
}
フィールド必須説明
type"FILE"はいファイルパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか
maxBytesnumberいいえ最大バイト数

JSONパラメーター(gRPCアクションのみ)

{
  type: "JSON",
  name: "statusFilter",
  valueType: "TEXT",
  selectOptions: [
    { label: "有効", value: "ACTIVE" },
    { label: "無効", value: "INACTIVE" },
  ],
}
フィールド必須説明
type"JSON"はいJSONパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
valueType"TEXT" | "NUMBER" | "DATE"はいJSONとして送信する値の型

valueTypeに応じて、TEXT/NUMBER/DATEパラメーターと同様のフィールドが追加で指定できます(requiredを除く)。

SYSTEM_VALUEパラメーター

ログイン中のユーザーIDなど、システムが提供する値を自動的に埋め込むパラメーターです。

{
  type: "SYSTEM_VALUE",
  name: "currentUserId",
  required: true,
}
フィールド必須説明
type"SYSTEM_VALUE"はいシステム値パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
requiredbooleanいいえ必須かどうか

ARRAYパラメーター

複数要素を配列として入力するパラメーターです。childElementで要素の型を、formatTypeで送信時の形式を指定します。

{
  type: "ARRAY",
  name: "targetIds",
  formatType: "JSON",
  childElement: { type: "NUMBER" },
}
フィールド必須説明
type"ARRAY"はい配列パラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
formatType"RAW" | "JSON" | "SEPARATOR"はい送信時の形式
childElementElementConfigはい要素の型(TEXT / NUMBER / DATE / ARRAY / TUPLE
minItemsnumberいいえ最小要素数
maxItemsnumberいいえ最大要素数
delimiterstringformatType: "SEPARATOR"のみ区切り文字
quoteCharacterstringformatType: "SEPARATOR"のみ引用符

gRPCアクションではformatType: "RAW"は使用できません。

TUPLEパラメーター

複数のフィールドを1つのパラメーターとしてまとめるタプル型のパラメーターです。

{
  type: "TUPLE",
  name: "filter",
  formatType: "JSON",
  tupleElements: [
    { label: "開始日", childElement: { type: "DATE" } },
    { label: "終了日", childElement: { type: "DATE" } },
  ],
}
フィールド必須説明
type"TUPLE"はいタプルパラメーターを指定
namestringはいパラメーター名
descriptionstringいいえ説明
formatType"RAW" | "JSON"はい送信時の形式
tupleElements{ label?: string; childElement: TupleChildElementConfig }[]いいえ各要素の定義

tupleElementschildElementにはTEXT / NUMBER / DATE / BOOLが指定できます。gRPCアクションではformatType"JSON"のみが指定可能です。