AIに聞く
すべてのカテゴリー
操作ガイド
カスタム連携を設定する

カスタム連携を設定する

最終更新日 January 22, 2026

1️⃣はじめに

カスタム連携とは

カスタム連携では、デクセコが連携に対応していないSaaSや、ユーザー企業様社内にあるシステムやファイルとの各種連携を可能にします

 

現在カスタム連携に対応しているのは以下の連携です

  • アカウント連携
  • メンバーマスタ連携
  • IT資産マスタ連携
 

カスタム連携では、ユーザー様が任意のホストマシンで「ランナー」を実行し、そのランナーで実行するスクリプトコードをデクセコから登録します。スクリプトコードはランナー上で実行されるため、ランナーを起動しているホストマシンから到達できるネットワーク内に連携したいシステムがあれば、アカウント連携をすることが可能です。

💡

カスタム連携を利用するには、TypeScriptやDenoの知識が必要です。

 

システム構成イメージ

Notion image
 

2️⃣カスタム連携を利用するには

1. ランナーを実行するホストマシンの準備

ランナーの実行には、Denoのインストールが必要です。Denoのインストール方法から各OSに合ったインストール方法を選択し、インストールをしてください。以下はWindowsのPowershellを使ったインストールコマンドの例です。

WindowsのPowershellを使ったインストール例
irm https://deno.land/install.ps1 | iex
 
⚠️
Denoについては公式サイトをご確認ください。Denoは、TypeScriptおよびJavaScriptのコードを簡単かつ安全に実行できるランタイム環境です。Node.jsに比べてセキュリティ機能が強化されており、モジュール管理も改善されています。
 

Denoのインストールが終わったら、以下のコマンドを実行しDenoコマンドが実行できるかを確認してください

$ deno --version
deno 1.44.4 (release, x86_64-pc-windows-msvc)
v8 12.6.228.9
typescript 5.4.5
 

2. ランナーの実行

💡

予めデクセコ上からAPIキーを発行してください（参考: APIを利用する）

 

ホストマシンで、以下のコマンドを実行します

deno run --reload -A https://raw.githubusercontent.com/oro-creation/dxeco-runner-v2/main/cli.ts --api-key "{APIキー}" --name "{任意のランナー名}"
⚠️
-A オプションは、すべての権限をランナーに与えます。ランナーで実行したい処理に応じて権限を絞ることができます。詳しくはPermissionを参照してください
 

カスタム連携のテスト時は以下のオプションを付けてランナーを起動することをおすすめします（カスタム連携の実行開始が速くなり、テストのトライ＆エラーがし易くなります）

--interval=5000

これで、ランナーが起動し、デクセコにランナーが登録されます

ランナーのソースコードはGitHubで公開をしております

 
⚠️
注意

カスタム連携は、常に指定したランナーで実行されます。ランナーは常時起動するようにしてください。ランナーが起動していない場合、連携は「ランナーがアクティブではありません」といった内容で失敗します

3. カスタム連携の設定

デクセコ側で、カスタム連携を設定します。

デクセコが標準で連携に対応していない場合、カスタム連携を設定できます。

 

カスタム連携の設定画面

 

アカウント連携の場合

「契約SaaS詳細」もしくは「アカウント」画面から設定できます。

メンバーマスタ連携の場合

メニュー> Settings > メンバーマスタ連携の画面から、「カスタム連携」より設定できます。

Notion image
 

IT資産マスタ連携の場合

メニュー > Settings > IT資産マスタ連携の画面から「カスタム連携により設定できます」

💡

カスタムIT資産マスタ連携は、カスタム連携設定時に、通常のIT資産マスタ連携同様に連携対象のIT資産マスタを選択する必要があります

Notion image

カスタム連携に使用するランナーとスクリプトコードの設定について

いずれの連携種別においても、カスタム連携設定画面では、以下のような画面が表示されます。

ここで、スクリプトコードを実行するランナーと、スクリプトコードを記述します。

このスクリプトコードが返したデータが実際にデクセコ上のデータとして取り込まれます（例えばアカウント連携の場合、アカウント情報を返すことで、デクセコ内にアカウント情報として取り込みがされます）

右部にある「サンプルコードから選択」で、サンプルとなるコードを引用することも可能です

Notion image
 

ランナーを選択します。先程のランナーの起動が成功している場合、ここにランナー名の一覧が表示されます（表示されない場合、もう一度ランナーの起動を試し、右側のリロードボタンをクリックしてください）

Notion image
 

デフォルトのサンプルコードが初期値で記述されているため、そのまま「テスト実行」をクリックします。しばらくすると、サンプルコードがランナー上で実行され、結果が表示されます。

Notion image
 

ランナー側でも、実行されていることがログから確認できます

例
例
 

何らかのエラーが発生した場合、以下のようにエラー内容が表示されます

Notion image

以下は現在提供しているサンプルコードの一覧です

サンプルコード名
概要
デフォルト
固定のデータを返すサンプルコード
kyを使ったREST APIの呼び出し(dxeco)
kyライブラリを使い、REST APIを呼び出すサンプルです。例として、デクセコAPIからメンバー一覧を取得します。デクセコ以外のAPIを呼び出すように修正するなど、適宜書き換えをしてください
CSVファイルからの取得
CSVライブラリを使い、ホストマシン上またはホストマシンから到達できるネットワーク上にあるCSVファイルを読み込み、アカウント一覧を取得します
astralを使ったWebスクレイピング(Figma)
astralを使い、Webスクレイピングを使ったログインと、アカウント一覧の取得を行います。コードはFigmaを参考にした例です
playwrightを使ったWebスクレイピング(Figma)
playwrightを使い、Webスクレイピングを使ったログインと、アカウント一覧の取得を行います。コードはFigmaを参考にした例です

スクリプトコードからデクセコに送ることのできるデータについて

以下は、各連携で実装するスクリプトコードが返すべきデータのフィールドの説明です

カスタムアカウント連携

 

新仕様の型定義

ランナーが postMessage で返すデータの型情報です。完全な型定義は runner v2 の type.ts で公開されています。

AccountAdaptorResult（ランナーが postMessage で返すデータの入れ物）

フィールド名
型
説明
fields
AdaptorCustomField[]
情報項目（カスタムフィールド）定義一覧。契約SaaSの accountCustomFields に upsert（連携由来として自動印付け）。既存 code は name/type を上書きしないし、ランナーが返さなくなった code も削除されない（永続化）。
accounts (必須)
AdaptorAccount[]
アカウント一覧。従来の AdaptorAccount[] に情報項目値 values を付与したもの。

AdaptorAccount（SaaS側アカウント1件を表す型。従来型に情報項目値 values を追加）

フィールド名
型
説明
identifier
string
SaaS内でアカウントを一意に識別できる安定した識別子（更新・削除のキーになる）
code
string
社員番号
name
string
名前
email (必須)
string
メールアドレス
subemails
string[]
サブメールアドレス一覧
image
string
画像URL
type
‘Default’ | ‘NoCharge’
アカウントの種類（デフォルト値: Default） Default : 通常アカウント NoCharge: 無課金アカウント
lastActiveAt
string
最終アクティブ日時　※タイムゾーン付きのISO 8601形式 例: "2023-01-01T12:00:00+09:00"
canGetLastActiveAt
boolean
最終アクティブ日時が取得可能か
memo
string
メモ
tagNames
string[]
タグ名一覧（権限情報など）
actualCreatedAt
string
アカウント作成日時（ISO 8601）
url
string
SaaSのアカウント画面のURL
values
Record<string, string | number | Date | null>
情報項目値。キーは fields[].code と一致させる。定義に無いキーは同期時に自動フィルタ（無視）。
 

AdaptorCustomField（fields に渡す情報項目の定義）

フィールド名
型
説明
code (必須)
string
データ側の識別子。values のキーに使う
name (必須)
string
表示名（台帳の列見出し）
type (必須)
‘Text’ | ‘MultipleText’ | ‘Option’ | ‘Status’ | ‘Date’ | ‘DueDate’ | ‘DateSpan’ | ‘Number’ | ‘Currency’ | ‘Email’ | ‘MemberEmail’ | ‘File’ | ‘MultipleFile’ | ‘Asset’
情報項目の種類。 Text / MultipleText: テキスト Option: options[] を選択肢にするドロップダウン Status: statuses[] を選択肢にする色付きバッジ（マトリクスに表示できる） Date / DueDate / DateSpan: 日付 Number / Currency: 数値 / 金額 Email / MemberEmail: メールアドレス
options
string[]
type: "Option" のときの選択肢
statuses
CustomFieldStatus[]
type: "Status" のときのステータス一覧
numberOfDaysBeforeWarning
number
type: "DueDate" のときの警告表示前日数

CustomFieldStatus（statuses に渡すステータス定義）

フィールド名
型
説明
code (必須)
string
ステータスコード（values に入れる値）
name (必須)
string
ステータス名（画面表示）
color
string
色（HEX、例: "#F5A800"）
⚠️

キーの一致ルール

  • AdaptorAccount.values のキーは AdaptorCustomField.code と一致させる（name や日本語ラベルではなく code）
  • type: "Status" の値には statuses[].code を入れる（name ではない）
  • type: "Option" の値には options[] に含まれる文字列 を入れる
 
旧仕様（廃止予定）
フィールド名
型
説明
identifier
string
連携先SaaSの識別子情報（ID情報など）
name
string
アカウント名
email (必須)
string
アカウントのメールアドレス
subemails
string[]
アカウントのサブメールアドレス一覧
image
string
アカウントの画像URL
type
‘Default’ | ‘NoCharge’
アカウントの種類 (※デフォルト値: Default) Default : 通常のアカウント NoCharge: 無課金アカウント
lastActiveAt
string
最終アクティブ日時　※タイムゾーン付きのISO 8601形式 例: "2023-01-01T12:00:00+09:00"
tagNames
string[]
タグ名一覧（権限情報など）

情報項目（カスタムフィールド）付きのカスタムアカウント連携

契約SaaSごとに保持したい情報項目（権限ロール・ライセンス種別 など）は、postMessage に { fields, accounts } の形で渡すことで、アカウント一覧と一緒に定義・登録できます。

サンプルコード

import type {
  AccountAdaptorResult,
  AdaptorAccount,
  AdaptorCustomField,
} from "https://raw.githubusercontent.com/oro-creation/dxeco-runner-v2/main/type.ts";

onmessage = () => {
  // このSaaSに置きたい情報項目の定義
  const fields: AdaptorCustomField[] = [
    {
      code: "role",
      name: "権限ロール",
      type: "Status",
      statuses: [
        { code: "admin",  name: "管理者" },
        { code: "member", name: "一般" },
      ],
    },
    { code: "license", name: "ライセンス", type: "Text" },
  ];

  // SaaS側から取得したアカウント一覧（従来の AdaptorAccount[] に情報項目値 values を付けたもの）
  const accounts: AdaptorAccount[] = [
    {
      identifier: "u_00001",
      email: "admin@example.com",
      name: "管理者太郎",
      values: { role: "admin", license: "Pro" },
    },
    {
      identifier: "u_00002",
      email: "user@example.com",
      name: "一般花子",
      values: { role: "member", license: "Free" },
    },
  ];

  const result: AccountAdaptorResult = { fields, accounts };
  postMessage(result);
};

取り込み時の振る舞い

  • fields は契約SaaSの accountCustomFields に upsert されます（連携由来として自動印付け）。既存の code は name/type は上書きせず、ランナーが返さなくなった code も削除されません。
  • 各アカウントの values のキーは fields[].code と一致させます。定義に存在しないキーは同期時に自動でフィルタされます（無視）。
  • 旧仕様 postMessage(accounts)（AdaptorAccount[] を直接渡す）も互換のため受理されますが、新規は上記の { fields, accounts } を推奨します。

情報項目の型指定パターン

型
fields の例
values の入れ方
Status（色付きバッジ、アカウント一覧マトリクスに表示できる）
{ code: "role", name: "権限ロール", type: "Status", statuses: [{ code: "admin", name: "管理者" }] }
values: { role: "admin" }（statuses[].code を指定）
Option（ドロップダウン）
{ code: "license", name: "ライセンス", type: "Option", options: ["Free", "Pro", "Business"] }
values: { license: "Pro" }
Text / MultipleText
{ code: "department", name: "部署", type: "Text" }
values: { department: "開発部" }
Date / DueDate / DateSpan
{ code: "joinedAt", name: "参加日", type: "Date" }
values: { joinedAt: new Date("2026-04-01") }
Number / Currency
{ code: "seatCount", name: "座席数", type: "Number" }
values: { seatCount: 123 }
Email / MemberEmail
{ code: "managerEmail", name: "上長", type: "MemberEmail" }
values: { managerEmail: "boss@example.com" }

カスタムメンバーマスタ連携

フィールド名
型
説明
identifier
string
連携先SaaSの識別子情報（ID情報など）
code
string
社員番号
email (必須)
string
メールアドレス
name
string
名前
department
string
部署
position
string
役職
subemails
string[]
サブメールアドレス一覧
image
string
画像
values
Record<string, string | number | null> (※カスタムフィールドのコードと値のRecord)
カスタムフィールド値
 

カスタムIT資産マスタ連携

フィールド名
型
説明
fieldMdmToolDeviceId
string
IT資産の識別に使うフィールドコード ※このフィールド同士が一致するIT資産が存在する場合は、そのIT資産の値を上書きします。存在しない場合は新規で作成します
fields
ReadonlyArray<AdaptorCustomField>
連携するフィールド一覧
assets
ReadonlyArray<AdaptorAsset>
連携するIT資産一覧 ※IT資産のフィールド値のうち、連携されるのはfieldsに含まれるフィールドのみとなります 型情報の詳細は@oro-creation/dxeco-runner-v2のtypes.tsをご覧ください
 

カスタム連携の作成が完了したら、保存をクリックします。

同期が実行され、データが取り込まれます

アカウント連携の場合
アカウント連携の場合
 

カスタム連携を修正したい場合、同じくツールチップから「カスタム連携を編集する」を選択してください

Notion image
 

実行頻度について

設定されたカスタム連携は

通常の連携機能と同様に設定直後、もしくは日次で夜間に実行されます。

実行を停止したい場合は、カスタム連携設定の削除を行ってください。

 

以上が、カスタム連携のご説明となります。ご不明点がございましたらデクセコ担当者にご連絡ください

トラブルシューティング

⚠️Webスクレイピングでブラウザが起動しない旨のエラーが出る

ランナーでWebスクレイピングを実行する場合、ホストマシンのOSによっては別途ブラウザをインストールする必要になることがあります。Ubuntuの例だと、以下のコマンドを実行し、chromiumをインストールしてください

sudo apt update
sudo apt install chromium-browser

Webスクレイピングのコード側では

const browser = await launch({
  path: '/usr/bin/chromium-browser',
  args: [
    '--headless=new', // ヘッドレスモードで実行する場合は追加
    '--ignore-certificate-errors', // 自己証明書の警告をスキップしたい場合は追加
    '--no-sandbox', // rootユーザーで実行する場合は必須で追加
  ]
});

という様にブラウザの実行ファイルをpathで指定してください

補足情報

ランナーのソースコード

ランナー自体のソースコードはGitHubで公開をしております

操作イメージ動画

 
解決しましたか?
😞
😐
🤩
IP制限をする チームを管理する