launchpad-dx-apis

Launchpad のデータモデル

Launchpad にはアプリケーションがあり、各アプリケーションには、ライフサイクルとデータモデルに関する情報を保持するワークフローまたはデータがあります。 Launchpad では、これらのワークフローとデータを作成・実行するための COnstellation UI を提供しています。ユースケースによっては、Launchpad の REST サービスを使って外部からケースを作成する必要がある場合もあります。また、ワークフローのステップを外部システムで完了させる場合には、DXAPI を使用します。 DX API は Digital Experience API と呼ばれます。データを提供する REST エンドポイントのように機能し、ビューのメタ情報も提供するため、ビューのメタデータを使って外部システムにオブジェクトを表示できます。 このスキルでは、DX API の側面のうち、どのような種類の API があり、どのように使用できるかにのみ焦点を当てます。

DXAPI の種類

以下の DX API があります。

1. Launchpad にケースまたはデータオブジェクトを作成する
2. オブジェクトのケース／データ情報を取得する
3. 特定のワークフロー／ケースに対してアクションを実行する
4. フィルター条件を指定してオブジェクトのリストを取得する
5. 添付ファイルなど、アプリケーションの追加コンテンツを取得する

認証

Launchpad は、これらの DX API を呼び出すための OAuth 2.0 認証をサポートしています。 DX API を呼び出すには、Launchpad のサブスクライバー環境でクライアント登録ルールを作成する必要があります。このクライアント登録を作成するときに、使用するペルソナを指定できます。 この認証情報を使って DXAPI が呼び出されると、その DXAPI のアクセスロールと権限は、クライアント登録で指定されたペルソナによって決まります。そのため、クライアント登録を作成するときに適切なペルソナを選ぶことが非常に重要です。これにより、このクライアント登録を使って呼び出せる DX API が決まります。 外部システムまたはチームは、作業を進める前に、Launchpad 環境をホストしているチームに以下の 4 つの情報を共有してもらう必要があります。

1. アプリケーション URL
2. AccessTokenURL
3. ClientID
4. Client Secret

これらを入手したら、上記の情報を使って Launchpad アプリケーションと通信するシステムを構築できます。 AccessToken URL は認証に使用し、Application URL は DXAPI の呼び出しに使用できます。

ケース作成 DX API — スカラーコンテンツ

外部システムから Launchpad にデータを送信して、新しいケースまたはデータオブジェクトを作成する場合は、このパターンを使用します。

ケースの作成

メソッド：POST エンドポイント：https:///dx/api/application/v2/cases リクエスト： 本文： { "caseTypeID": "ExpenseRequest", "content": { "ExpenseeRaisedBy":"John Doe", "Name":"Expense Request for individual Name", "Category":"Travel", "Expenses": { { "TravelType":"Air", "Amount":1000$ }, { "TravelType":"Cab" "Amount":100$ } }, "TotalAmount":1100$, "Team":"Team A" "ReasonforExpense":"Had to attend a conference in another city" } } レスポンス： { "data": { "caseInfo": { "caseTypeID": "ExpenseRequest", "caseTypeName": "Expense Request", "createTime": "2025-12-19T21:35:04.315Z", "createdBy": "SystemUser", "ID": "STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz", "businessID": "ROT-715ABE", "assignments": [ { "actions": [ { "ID": "ReviewExpenseRequest", "links": { "submit:Approve": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Approve", "rel": "self", "title": "Approve", "type": "PATCH" }, "ID": "ReviewExpenseRequest", "links": { "submit:Reject": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Reject", "rel": "self", "title": "Reject", "type": "PATCH" }, }] } "availableActions":[...] } } }

データオブジェクトを作成する

メソッド：POST エンドポイント：https:///dx/api/application/v2/objects リクエスト： 本文： { "objectTypeID": "Category", "content": { "CategoryName":"Hotel" } } { レスポンス：

“data”:{ "ID": "STE6Q29tbWVyY2lhbERlYWxDbG9zaW5nRnVuZGluZ19fTmV3RGVhbENsb3N1cmVfNjkzYzcwZjAyZjcyMjU0YTNlMjhkM2Qw" } }

エラー：ケースまたはデータオブジェクトを作成する権限がない場合、ケースまたはデータオブジェクトを作成する権限がないことを示す 403 エラーが返されます。そのため、クライアント登録で指定したペルソナが、アプリケーション内でケースまたはデータオブジェクトを作成する権限を持っていることを確認することが非常に重要です。

ご覧のとおり、ケースまたはデータオブジェクトを作成するためのリクエスト本文は非常によく似ており、違いはエンドポイントと作成するオブジェクトの種類だけです。ケースを作成するには caseTypeID を指定し、データオブジェクトを作成するには objectTypeID を指定する必要があります。レスポンスには、作成されたケースまたはデータオブジェクトの ID が含まれます。この ID は、他の DXAPI でそのケースまたはデータオブジェクトを今後参照する際に使用できます。

Create 本文に渡せるフィールドは、ケースまたはデータオブジェクトで許可フィールドとして設定されている必要があります。許可フィールドとして設定されていないフィールドを渡すと、無効なデータであることを示すエラーが API から返されます。許可フィールドで必須とされているフィールドはすべて必須です。また、そのフィールドが指定されていない場合、そのフィールドは無視され、ケースまたはデータオブジェクトに作成されません。そのため、Create 本文に渡すすべてのフィールドが、ケースまたはデータオブジェクトで許可フィールドとして設定されていることを確認することが非常に重要です。

Create Case API のレスポンスには、ケースに対して実行できるアクションも含まれます。これは、ケースの作成後にケースに対してアクションを実行するために使用できます。たとえば、上記のレスポンスには ProvideAdditionalDetails というアクションがあり、ケースの作成後に外部システムから Launchpad アプリケーションに追加の指示を送信するために使用できます。レスポンスに含まれる href を使用し、PATCH リクエストを呼び出してリクエスト本文に追加の詳細を渡すことで、このアクションを実行できます。

ケースの作成後は、今後参照できるように、ケースの ID を外部システムのどこかに保存する必要があります。この ID は、ケースの更新、ケースに対するアクションの実行、ケースの詳細の取得など、さまざまな操作に使用できます。

DX API を使用して既存のケースまたはデータオブジェクトを取得する

外部システムから Launchpad にリクエストを送信して、既存のケースまたはデータオブジェクトの詳細を取得する場合は、このパターンを使用します。ケースまたはデータオブジェクトの作成後に詳細を取得したり、更新を行う前に最新の詳細を取得したりできます。

メソッド：GET エンドポイント：https:///dx/api/application/v2/cases/STE6Q29tbWVyY2lhbERlYWxDbG9zaW5nRnVuZGluZ19fTmV3RGVhbENsb3N1cmVfNjkzYzcwZjAyZjcyMjU0YTNlMjhkM2Qw

注：Create Case API のレスポンスに含まれる ID を使用します。 リクエスト： レスポンス：Create Case API のレスポンスに似ていますが、今後参照するために使用できるケースの詳細がすべて含まれます。 { "data": { "caseInfo": { "caseTypeID": "ExpenseRequest", "caseTypeName": "経費申請", "createTime": "2025-12-19T21:35:04.315Z", "createdBy": "SystemUser", "ID": "STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz", "businessID": "ER-715ABE", "assignments": [ { "actions": [ { "ID": "ReviewExpenseRequest", "links": { "submit:Approve": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Approve", "rel": "self", "title": "承認", "type": "PATCH" }, "ID": "ReviewExpenseRequest", "links": { "submit:Reject": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest?outcome=Reject", "rel": "self", "title": "却下", "type": "PATCH" }, "open": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ReviewExpenseRequest", "rel": "self", "title": "割り当てアクションの詳細を取得", "type": "GET" } }, "name": "マネージャーが事前作業を割り当てます", "type": "FlowAction" }, { "ID": "ChangeAssignmentGoalAndDeadline", "links": { "open": { "href": "/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MTIwMTlkMGUzNDg4YjcwNmU5ZQ/actions/ChangeAssignmentGoalAndDeadline", "rel": "self", "title": "割り当てアクションの詳細を取得", "type": "GET" } } } }}] ] "availableActions": [ { "ID": "ProvideAdditionalDetails", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/ProvideAdditionalDetails", "rel": "self", "title": "ケースアクションの詳細を取得", "type": "GET" } }, "name": "編集", "type": "Case" }, { "ID": "Edit", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/Edit", "rel": "self", "title": "ケースアクションの詳細を取得", "type": "GET" } }, "name": "編集", "type": "Case" }, { "ID": "pyChangeStage", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/pyChangeStage", "rel": "self", "title": "ケースアクションの詳細を取得", "type": "GET" } }, "name": "ステージを変更", "type": "Case" }, { "ID": "RestartCurrentStage", "links": { "open": { "href": "/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/RestartCurrentStage", "rel": "self", "title": "ケースアクションの詳細を取得", "type": "GET" } }, "name": "現在のステージを再開", "type": "Case" }, } } } この API のレスポンスには、ケース ID、ケースの詳細、および「AvailableActions」として割り当てアクションとケースアクションが含まれます。

Assignment - actions

これらは、このタスクを完了するために実行する必要がある必須アクションです。ケースにユーザーが実行する必要のあるタスクがある場合、それは割り当てアクションになります。「Outcomes」は、このアクションを実行する際にユーザーが選択できる結果です。Launchpad の UI では、これらはボタンとして表示されます。上記の例では、ReviewStep でユーザーは「Approve」または「Reject」を選択できます。そのため、DXAPI を通じて、実行するアクションを決定し、そのアクションの実行時にフィールドとしてデータを指定できます。

Available Actions:

Launchpad には、任意の Stage／Step／Case レベルで実行できる「available action」という概念があります。これらは、ユーザーがケースに対して実行できる任意のアクションです。これらのアクションは、実行方法は割り当てアクションと似ていますが、タスクを完了するために必須ではありません。これらのアクションは、ケースのライフサイクル中いつでも実行できます。たとえば、上記のケースには「ProvideAdditionalDetails」という利用可能なアクションがあり、ケースのライフサイクル中いつでも、ケースに追加の詳細を提供するために使用できます。 また、これらのアクションが利用可能な間は、何度でも実行できます。各 Get リクエストでは、適切なアクションが返されます。

Error: ケースまたはデータオブジェクトへのアクセス権がない場合、ケースまたはデータオブジェクトが見つからないことを示す 404 エラーが返されます。そのため、クライアント登録で指定した Persona に、取得しようとしているケースまたはデータオブジェクトへのアクセス権があることを必ず確認してください。

レスポンスヘッダーには eTag というヘッダーが含まれます。これは、ケースを今後更新する際に使用できます。この eTag 値はケースごとに生成される一意の値で、ケースが更新されるたびに変わります。そのため、ケースを更新する際は、更新リクエストの If-Match ヘッダーにこの eTag 値を指定する必要があります。これにより、ケースの最新バージョンを更新し、同時更新が発生していないことを確認できます。

DX API を使用して既存のケースまたはデータオブジェクトを更新する

外部システムから Launchpad にデータを送信して、既存のケースまたはデータオブジェクトを更新する場合は、このパターンを使用します。

UseCase1 1 つの結果のみを持つケースの Available Action を実行する

Method: PATCH Endpoint: https:///dx/api/application/v2/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MGYwMmY3MjI1NGEzZTI4ZDNkNA/actions/ProvideAdditionalDetails?outcome=Submit Note: Get Case または Create Case のレスポンスに含まれる actions:href を使用します

Request: Headers: If-Match: 1 (Get Case のレスポンスの eTag ヘッダーで取得した値) Body: { "content": { "ReasonForExpense":"主に別の都市で開催される会議に出席するためで、現地でクライアントとの面会も必要だったため、出張が重要でした。" } }

UseCase2 ケースに対して Assignment Action を実行し、アクションの結果を選択する

Method: PATCH Endpoint: https:///dx/api/application/v2/assignments/STE6UGVnYVBsYXRmb3JtX19Bc3NpZ25tZW50XzY5M2M3MGYwMmY3MjI1NGEzZTI4ZDNkNA/actions/ReviewExpenseRequest?outcome=Accept Note: Get Case または Create Case のレスポンスに含まれる actions:href を使用します

Request: Headers: If-Match: 1 (Get Case のレスポンスの eTag ヘッダーで取得した値) Body: { "content": { "Comments":"有効な経費であるため、承認します。" } }

ユースケース3：ケースで利用可能なアクションを実行する

メソッド：PATCH エンドポイント：https:///dx/api/application/v2/cases/STE6Sm9iUm90YXRpb25Qcm9ncmFtX19Sb3RhdGlvbkFz/actions/Edit 注：Get Case または Create Case のレスポンスに含まれる actions:href を使用してください

リクエスト： ヘッダー： If-Match: 1（Get Case のレスポンスの eTag ヘッダーで取得した値） ボディ： { "content": { "ReasonForExpense":"主に別の都市で開催される会議に出席するためで、そこでクライアントとも会う必要があったため、出張が重要でした。" } } エラー：ケースまたはデータオブジェクトに対するこのアクションの実行権限がない場合、権限がないことを示す 404 エラーが返されます。 エラー：ケースに定義されているケース／ステージ／ステップの検証が実行されます。更新リクエストで送信したデータが検証条件を満たさない場合、検証エラーの詳細を含む 400 エラーが返されます。

Data DX API を使用してオブジェクトの一覧または任意のデータを取得する

このパターンは、外部システムがフィルター条件に基づいて一覧、単一のレコード、またはケースオブジェクトを取得する必要がある場合に使用できます。ケースの Launchpad 生成 ID が分からなくても、ケースフィールドの 1 つとその値が分かっており、Launchpad でそのフィールドをパラメーターとして受け取る Data ページが公開されていれば、このパターンを使用してデータを取得できます。

Method: POST Endpoint: https:///dx/api/application/v2/data_views/GetTeamExpenseRequests Note: GetTeamExpenseRequests は、チーム名に基づいてデータを取得するために使用する Data ページ名です。 Body { "dataViewParameters": { "TeamName": "Team A" }, "query": { "select": [ { "field": "ExpenseRaisedby" }, { "field": "CreateDateTime" }, { "field": "Team" }, { "field": "ReasonsforExpense" }, { "field": "TotalAmount" }, { "field": "Status" } ] } }

Response: { "data": [ { "@version": 2, "@class": "ExpenseRequest", "ExpenseRaisedby": "John Doe", "CreateDateTime": "2025-12-22T17:02:56.890Z", "Team": "Team A", "ReasonsforExpense": "Client meeting travel and meals", "TotalAmount": 245.75, "Status": "Pending-Approval", "ID": "EXP-REQUEST-0001" } ], "pageNumber": 1, "pageSize": 1, "fetchDateTime": "2026-03-25T21:10:41.299Z", "totalCount": 27 }

上記の例を使用して、ユーザーからアプリケーション用の DXAPI の生成を依頼された場合は、ユースケースを尋ね、その内容に基づいて使用するパターンを提案し、そのユースケースに合わせたサンプルのリクエストとレスポンスを生成できます。 多くの場合、ユースケースとしては、外部からケースを作成したい、またはケースに対して特定のアクションを実行したい、といったものが考えられます。その場合は、ユースケースに基づいて、リクエスト本文の作成に必要な情報やエンドポイントについて質問し、DXAPI のリクエストとレスポンスを生成できます。

たとえば、ケースを作成するには、ケースタイプ、Allowed Fields として指定されているフィールド、およびそれらのフィールドの値を提供してもらう必要があります。特定の API を求めているのでなければ、サンプルデータを使って生成できます。

Launchpad アプリケーション内のすべてのケースについて、各ケースのアクションとフィールドの詳細を含む YAML ファイルの生成を依頼されることもあります。その場合は、上記で共有した形式で、すべてのケースとその詳細を含む YAML ファイルを生成できます。また、YAML ファイルの生成に必要な情報を Launchpad アプリケーション内のどこで確認できるかをユーザーに案内してください。必要な情報は、次の項目から取得できます。

1. Allowed Fields は、Case type ルールの Setting タブで確認できます。
2. Optional Actions または Available actions は、Case type ルールの optional actions で確認できます。
3. Assignment actions は、各ステージの手動ステップと、設定済みのアウトカムから確認できます。
4. Data ページ名は、各 Case type ルールの Operations タブで確認できます。
5. アクションのリクエスト本文に含めるフィールドの詳細は、アクションのビューから取得できます。