埋め込みPanelアプリを作成する

Coupaで特定のページのPanelアプリを作成する方法を学びます。

はじめに

Panelアプリを使用すると、お客様は特定のCoupaページのUIパネル内に外部ソースからのデータを表示できます。 このデータはコンテキスト固有で、自動または手動で更新できます。たとえば、サプライヤーページがCoupaでロードされると、そのページのPanelアプリは、特定のサプライヤーに関連するAPIを介して外部ソースからデータを自動的に取得し、Coupaでデータを表示できます。

Panelアプリを作成するには、 設定 > プラットフォーム > インストール済みアプリ をクリックし、 作成 ボタンをクリックし、次のオプションを選択します。 新規Panelアプリを作成 。Panelアプリを作成、設定する際に重要なのは、アプリのパラメーターのJSON形式セットである記述子を使用することです。

これはCoupaホームページのPanelアプリの例です。

CoupaホームページのPanelアプリの例

Panelアプリを作成するには、 設定 > プラットフォーム > インストール済みアプリ 。[作成]ボタンをクリックし、 新規Panelアプリを作成

必要条件

R29以降、Panelアプリには少なくとも TLS v1.2 サードパーティAPIへのアウトバウンド接続を作成できます。

Panelアプリの基本

Panelアプリは、JSON形式を使用するアプリ記述子を使用して構築されます。記述子は、データとブロックの2つの主要なプロパティーで構成されています。データは次を使用して処理されます JQ v1.6

プロパティー 説明
slot

パネルがレンダリングされるページタイプを指定します。現在のオプション:

  • user.home (Coupaホームページ: / および /user/home できます。
  • suppliers.show (サプライヤー詳細ページ: /suppliers/:id/record できます。
  • items.show (アイテム詳細ページ: /items/{id} できます。
  • contracts.show (契約詳細ページ: /contracts/show/:id できます。
  • requisition_headers.edit (Coupaショッピングカート: /requisition_headers/{id}/edit できます。
  • invoices.show (次世代インボイスUIでのインボイスの編集を含むインボイス詳細ページ: /invoices/{id} および /invoices/{id}/show_for_approval できます。

  • receipts.full_receipt (詳細な受領書ページ: /receipts/{id}/full_receipt できます。

  • expenses.index (経費ランディングページ: /expenses できます。

  • projects.show (プロジェクト詳細ページ: /projects/{id} できます。

  • quotes/requests.show (ソーシングイベント詳細ページ: /quotes/requests/{id} できます。

  • asn/headers.show (事前出荷明細通知詳細ページ: /asn/headers/{id} できます。

  • receipts.full_receipt (受領書詳細ページ: /receipts/{id}/full_receipt できます。


{
	 "slot": "user.home"
 }

Panelアプリごとに指定できるスロットは1つだけです。アプリを複数のページに表示するには、目的のアプリを再度作成します slot 値を使用します。

data

データ属性は、パネルにレンダリングされた目的のデータをフェッチする方法を説明します。  パネルをレンダリングするためにフェッチするデータを説明するJSONオブジェクト。このオブジェクトの値は、データを取得するためにCoupaがリクエストを送信するURLになります。 これらすべてのデータ要求からの応答は1つのハッシュに統合され、このオブジェクトで指定されたキー名でエイリアスされます。


"data": {
		"study_queue": "https://www.wanikani.com/api/user/{user_ID}/study-queue",
		"level_progression": "https://www.wanikani.com/api/user/{user_ID}/level-progression"
	}
}
context


slot が表示されるページに関するコンテキスト詳細を提供します。たとえば、サプライヤーの表示ページに表示されているPanelアプリは、その特定のサプライヤーに関するコンテキストデータにアクセスできます。このコンテキスト情報はデータオブジェクトで使用できますが、で使用することはできません blocks 。 したがって、Panelアプリが「ACMEサプライヤー」の表示ページでレンダリングされると、サプライヤーの名前、Coupa ID、カスタムフィールド値、そのサプライヤーの他のプロパティに基づいてAPIコールをカスタマイズできます。

サプライヤーに関する最近の記事を検索するNYタイムズの記事の検索へのAPIコールは次のようになります。


"data": {
		"nyt_data": {
			"uri": "https://api.nytimes.com/svc/search/v2/articlesearch.json?
			q={context.supplier.name}&api-key={properties.api_key}"
	}
}			

各スロットで利用可能なコンテキストデータの更新リストについては、Coupaにお問い合わせください。

API呼び出しをパラメーター化(プロパティ)

Panelアプリを有効にした後にユーザー/管理者が提供する必要があるプロパティの配列。アプリ/APIで一意のAPIキー、または有効にするCoupa顧客ごとにログイン/パスワードが必要な場合、そのオプションの提供方法は次のとおりです。

ブロックの例は次のとおりです。


"properties": {
		"username": {
			"type": "string"
		},
		"password": {
			"type": "string"
		}
	}

次に、データブロックのプロパティを次のように参照します。


"data": {
		"my_data": {
			"method": "post",
			"uri": "https://someurl.com/EVToken",
			"body": "grant_type=password&username={{ properties.username }}&
			password={{ properties.password }}"
		}
	}

Coupa管理者が新しいPanelアプリを有効にすると、アプリ記述子で指定されたすべての「プロパティ」フィールドに入力するよう求められます。

launch

Panelアプリをすぐに表示する必要がない場合に使用できる起動ボタンを追加します。Panelアプリが自動的にサードパーティに連絡してデータをレンダリングするのではなく、エンドユーザーが手動で[起動]ボタンをクリックした場合にのみ連絡します。

このJSONオブジェクトには次が含まれます description button_text および help_text 。例:


"launch": {
		"description": "PretendCo Tax Calculator Service",
		"button_text": "Launch Calculator",
		"help_text": "Tax Calculator integrates with Coupa to help you calculate international 
		taxes, right in the cart."
	}

使用方法 launch で指定します。

  • Panelアプリのデータがページ内の特定のビジネスケースにのみ関連する場合に使用します
  • と同じレベルで追加 slot data 、など。ただし、 blocks
allow_refresh

ページのデータが変更され、Panelアプリでレンダリングされたデータに影響を与える場合に使用できる[更新]ボタンを追加します。 これは、申請書の品目が更新されたときにカートPanelアプリで便利です。ユーザーは[更新]ボタンをクリックして、Panelアプリのデータを更新できます。

これはブール値のオプションで、アプリ記述子のPanelアプリに更新ボタンを表示するために使用されます。

"allow_refresh": true

使用方法 allow_ refresh で指定します。

  • ユーザーがアプリに必要なデータを更新でき、アプリに新しいデータが必要な場合に使用します

ボタンをクリックすると、そのアプリのコンテンツが更新されます。このフィールドは「slot」、「data」、「launch」などと同じレベルに追加する必要がありますが、ブロック単位では追加できません。更新ボタンはパネルアプリケーションの上部に表示されます。

blocks

ブロック属性は、パネルでデータをレンダリングする方法を説明します。これは、さまざまなタイプのJSONオブジェクト(「ブロック」)の配列で、それぞれが個別のビジュアライゼーションを説明します。ブロックは、以前に送信されたデータにアクセスし、それを使用して視覚化を作成します。

error_blocks エラーブロック属性はブロック属性と同様に機能しますが、データの取得またはレンダリングに問題がある場合にエラーメッセージを作成するために使用されます。

データを取得中

アプリのデータをフェッチするために、アプリは最大5つの個別のHTTP呼び出しを作成できます。これらは、記述子のデータ属性を使用して指定されます。API呼び出しは、JSON(推奨)またはXMLを返す必要があります。

Panelアプリのブロックタイプ

Panelアプリは、既存のCoupaページにそのデータをレンダリングし、さまざまなタイプのUI要素( ブロック 。Coupaは以下のブロックタイプをサポートしています。

  • リッチテキスト(画像を含む)
  • フィールド(基本的にキーと値のペア)
  • 数字
  • 貨幣
  • 円グラフ
  • 折れ線グラフ/棒グラフ
  • 立ち上げ
  • 再読み込み

アプリケーション設定

属性 説明

type

ブロックのタイプを識別します。たとえば、 fields text 、または bars 。これにより、UIでのパネルのレンダリング方法とデータに必要なフォーマットが決定されます。

data

このJSONオブジェクトは戦略によって異なるプロパティーを持っています。

JQ

  • タイプは「jq」に等しくなければなりません

  • jqはJQスクリプトを含む文字列です。JQスクリプトは、データ属性からマージされたデータ構造を入力として供給され、ブロックタイプに必要なフォーマットに適合するJSON構造を生成する必要があります。

JQでデータを処理する

たとえば、次のJQスクリプトを使用していくつかの特定のデータピースを抽出し、別のJSONオブジェクトに再パッケージ化できます。


{
	 "username": ".study_queue.user_information.username",
	 "radicals": ".level_progression.requested_information.radicals_progress",
	 "kanji": ".level_progression.requested_information.kanji_progress"
}

これにより、次のJSONオブジェクトが生成されます。


{
	 "username": "example_user",
	 "radicals": 0,
	 "kanji": 0
}

詳細情報:

other properties

異なるブロックタイプには、そのブロックタイプに固有の他のプロパティーがあります。

Panelアプリのブロックタイプ

テキストブロック

属性 説明

type

以下と等しい text

template

テキストブロックタイプはLiquid Markdownテンプレートを使用します。テンプレートは最初にLiquidとして解析され、リクエストから返されたデータを補完します。次に、テンプレートはMarkdownとして再度解析され、HTMLが生成されます。

Markdownは安全なHTML生成方法を提供し、セキュリティ上の理由から、Coupaはテンプレート内のインラインHTMLをブロックします。ブロックの構成を保存するデータ列の最大制限以外の文字制限はありません。

Markdownでは、ヘッダー、インライン強調フォーマット、リスト、画像、リンク、ブロック引用が可能です。Coupaは、構文の強調表示とテーブルもサポートしています。

LiquidとMarkdownの取り扱いの詳細については、を参照してください Liquidテンプレート言語 および Markdownの習得

data

データ戦略は、単一のJSONオブジェクトを生成する必要があります。オブジェクト内のすべてのキーは、Liquidテンプレートで変数として使用できます。


{
	 "foo": "bar",
	 "fizz": {
			"buzz": "buzz"
	 }
}
ヒント

現在、テキストブロックはテーブル内のデータを表示する最良/唯一の方法で、 取り締まり テーブル形式。

フィールドブロック

プロパティー 説明

type

以下と等しい field

data

データ戦略は、ラベルと値の属性を持つJSONオブジェクトの配列を作成する必要があります。レンダリング時、ラベルはフィールドラベルとして使用され、値はフィールド値として使用されます。


[
	 {
			"label": "Foobar",
			"value": "fizzbuzz"
	 },
	 {
			"label": "Lorem Ipsum",
			"value": 42
	 }
]
title フィールドのリストの上に表示されるオプションのタイトル。

棒/折れ線ブロック

プロパティー 説明

type

以下と等しい bar または line

data

データ戦略は、配列の配列を生成する必要があります。テーブルブロックとは異なり、棒/折れ線グラフのデータは列指向になります。

各配列は、表示される一連のデータを表します。最初の要素はシリーズの名前で、残りの要素はシリーズのポイントです。


[{
		"name": "Year 1800",
		"data": [107, 31, 635, 203, 2]
 }, {
		"name": "Year 1900",
		"data": [133, 156, 947, 408, 6]
 }, {
		"name": "Year 2000",
		"data": [814, 841, 3714, 727, 31]
 }, {
		"name": "Year 2016",
		"data": [1216, 1001, 4436, 738, 40]
}]
axis x軸とy軸のラベルを設定できます。
title グラフの上に表示されるオプションのタイトル。
description 小さいテキストでグラフの下に表示されるオプションの説明。

円ブロック

プロパティー 説明

type

以下と等しい

data

データ戦略は、「棒/折れ線ブロック」セクションで説明されているように、配列の列指向の配列を作成する必要があります。



[{
		name: 'Chrome',
		y: 20.41,
		sliced: true,
		selected: true
	}, {
		name: 'Internet Explorer',
		y: 11.84
	}, {
		name: 'Firefox',
		y: 10.85
	}, {
		name: 'Edge',
		y: 4.67
	}, {
		name: 'Safari',
		y: 4.18
	}, {
		name: 'Sogou Explorer',
		y: 1.64
	}, {
		name: 'Opera',
		y: 2.8
	}, {
		name: 'Other',
		y: 2.61
}]
title グラフ上に表示されるオプションのタイトル。
description 小さいテキストでグラフの下に表示されるオプションの説明。

貨幣ブロック

プロパティー 説明

type

以下と等しい 貨幣

data データ戦略は、次の構造を持つJSONオブジェクトを生成する必要があります。
  • Amountは、通貨の金額を決定するためのJSONフロート。
  • Currencyは、通貨のISO 4217通貨コードを含む文字列。

{
	"amount": 42.0,
	"currency": "USD"
}
Title 数字の上に表示されるオプションのタイトル。
Description 小さいテキストで数字の下に表示されるオプションの説明。

数字ブロック

プロパティー 説明

Type

以下と等しい 数字

Data

データ戦略は、単一のJSON整数または浮動小数点を生成する必要があります。


42.0
Decimal 小数点の後に表示する小数点以下の桁数。既定は0です。
Title 数字の上に表示されるオプションのタイトル。
Description 小さいテキストで数字の下に表示されるオプションの説明。Panelアプリの例

カスタムフィールド

コンテキスト内オブジェクトのカスタムフィールドにアクセスするには、次の一般的な形式に従います。
context.<object>.custom_fields.<field_name>

場所 <field_name> フィールド名 カスタムフィールドの作成時にプロンプトを表示:

cf_fields.png

Supplierオブジェクトを確認しており、フィールド、電話番号があるため、次のように参照します。
context.supplier.custom_fields.phone_number

スロット カスタムフィールドアクセサー
契約。表示 context.contract.custom_fields.
projects.show context.project.custom_fields.
quotes/requests.show context.quote_request.custom_fields.
requisition_headers.edit context.requisition_header.custom_fields.
サプライヤー。表示 context.supplier.custom_fields.

カスタムフィールドは、次のような特定のオブジェクトを参照しないスロットには適用できません。

  • user.home
  • expenses.index

API詳細

認証

Coupaは次の認証タイプをサポートしています。

方法
標準APIキー

"data": {
		"nyt_data": {
			"uri": "https://api.nytimes.com/svc/search/v2/articlesearch.json?q={context.supplier.name}
						&api-key={properties.api_key}"
		}
	}
基本認証

"data": {
		"trip_data": {
			"uri": "https://someurl.net/trips",
			"headers": {"Authorization":"basic YOUR_BASE64_ENCODED_TOKEN_HERE"}
		}
	}
「before_data」リクエストを使用した短期トークンのリクエスト

"before_data": {
		"auth": {
			"method": "post",
			"uri": "https://someurl.com/MYToken",
			"body": "grant_type=password&username={{ properties.username }}&password={{ properties.password }}"
		}
	},
	"data": {
		"risk_data": {
			"uri": "https://someurl.com/MYData?integration_id=%22ID{context.supplier.id}%22",
			"headers": {
				"Authorization": "bearer {{ before_data.auth.access_token }}"
			}
		}
	}

API URL

  • URLはHTTPSである必要があります
  • URLはCoupaサーバーからアクセスできる必要があります(つまり、HEADリクエストが成功する必要があります)
  • URLは有効なLiquidテンプレートとして正常に解析する必要があります。これは補間を有効にするためです

APIリクエストの詳細

  • Liquidを使用してデータをURLに補間する場合、結果は有効なURLである必要があります
  • 返答コードは200または204である必要があります
  • リモートサーバーは5秒以内に応答する必要があります
  • 返答のコンテンツタイプは次のいずれかにしてください application/json または application/xml

ボタン

以下を設定できます。 起動ボタン ( launch )および [更新]ボタン( allow_refresh できます。 Panelアプリ用です。機能はブロックのように見えますが、技術的にはボタンはブロックではありません。ボタンの詳細については、 Panelアプリの基本 詳細については、を参照してください。

Panelアプリコンテキスト

次のページ用のPanelアプリを構築できます。

  • ホームページ: / および /user/home
  • サプライヤーページ: /suppliers/:id/record
  • 契約ページ: /contracts/show/:id
  • カート: /requisition_headers/{id}/edit
  • プロジェクトホームページ: projects.show
  • ソーシングイベント設定ページ: quotes/requests.show

各Panelアプリタイプには、それぞれ固有のコンテキストペイロードがあります。以下は、データの照合と検索のコンテキストとして使用される、PanelアプリAPIペイロードに表示されるフィールドです。

ページ 利用可能なフィールド
すべてのPanelアプリ user_instance (例:[ドメイン名].coupahost.com)はペイロードに含まれています。
ホームページ id email fullname login employee_number
請求書の表示/編集

invoice_id invoice_date invoice_number supplier_name supplier_number supplier_id

サプライヤーページ

id name display_name duns number tax_id website status

カスタムフィールド: object.supplier.custom_field_values_hash

契約ページ id parent_contract_id name number version supplier_id start_date status
カート カートPanelアプリのペイロードには、申請書ヘッダーAPIペイロードと同じフィールドが含まれます
プロジェクト すべてのプロジェクトシステムフィールドとカスタムフィールド
ソーシングイベント

id event_name event_commodity project_id supplier_id カスタムフィールドとタグ

Panelアプリの例

ニューヨークタイムズの記事検索

このアプリでは、ニューヨークタイムズからのサプライヤーに関する最近のニュースをサプライヤーのページに追加します。次を取得する必要があります NYT APIキー これを機能させるには

nyt-article-search.png

これはアプリを動かすコードです。

{
	"properties": {
		"api_key": {
			"type": "string"
		}
	},
	"slot": "suppliers.show",
	"before_data": {},
	"data": {
		"nyt_data": {
			"uri": "https://api.nytimes.com/svc/search/v2/articlesearch.json?q={context.supplier.name}&api-key={properties.api_key}"
		}
	},
	"blocks": [
		{
			"type": "text",
			"data": {
				"type": "jq",
				"jq": "{ \"docs\": .nyt_data | .response | .docs }"
			},
			"text": "![nyt logo](http://www.transervice.com/wp-content/uploads/2018/06/the-new-york-times-4.png){:height=\"100px\"}"
		},
		{
			"type": "text",
			"data": {
				"type": "jq",
				"jq": "{ \"docs\": .nyt_data | .response | .docs }"
			},
			"text": "1. [{{ docs[0].headline.main }}]({{ docs[0].web_url }}) \n2. [{{ docs[1].headline.main }}]({{ docs[1].web_url }})\n3. [{{ docs[2].headline.main }}]({{ docs[2].web_url }})\n4. [{{ docs[3].headline.main }}]({{ docs[2].web_url }})\n5. [{{ docs[2].headline.main }}]({{ docs[4].web_url }})\n"
		}
	]
}

Weather Panelアプリ

このサンプルアプリは、場所の温度の側面をグラフィカルに表示します。次を取得する必要があります API キー これを機能させるには

weather-app-example.png

これはアプリを動かすコードです。

{
	"properties": {},
	"slot": "suppliers.show",
	"data": {
		"chicago_data": {
			"method": "get",
			"uri": "https://api.openweathermap.org/data/2.5/weather?q=Chicago&appid=155057bc8e3dde82a6482e76bddf9c10&units=imperial"
		}
	},
	"blocks": [
		{
			"type": "bar",
			"title": "Here's the weather in Chicago",
			"data": {
				"type": "jq",
				"jq": "[{name: \"Temp\", data: [.chicago_data.main.temp]}, {name: \"Wind Speed\", data: [.chicago_data.wind.speed]}, {name: \"Humidity\", data: [.chicago_data.main.humidity]}]"
			},
			"axes": {
				"xAxis": {
					"labels": {
						"enabled": false
					}
				},
				"yAxis": {
					"title": {
						"text": ""
					},
					"max": 100
				}
			}
		},
		{
			"type": "line",
			"title": "Here's the weather in Chicago",
			"data": {
				"type": "jq",
				"jq": "[{name: \"Minimum, Current, max temp for Chicago\", data: [[.chicago_data.main.temp_min], [.chicago_data.main.temp], [.chicago_data.main.temp_max]] }, {name: \"Fake data not from API\", data: [44, 52, 130, 87, 74, 88] }]"
			},
			"axes": {
				"xAxis": {
					"labels": {
						"enabled": true
					},
					"categories": [
						"Jan",
						"Feb",
						"Mar",
						"Apr",
						"May",
						"June"
					]
				},
				"yAxis": {
					"title": {
						"text": ""
					},
					"max": 200
				}
			}
		}
	]
}

PanelアプリAPIの例

以下は、自動テストに使用されるアプリ記述子です。API応答を省略して、次のように正確に返します。

[	
	{	
		"data_title":"Title",
		"data_number":42,
		"second_score":88
	}
]
 
{
	# Here is where you'd setup client specific fields. Like login/password. The customer would be prompted to fill in
	# those values once, when activating the application
	"properties": {},
	# This is the page where the app gets displayed. See the "slot" property for possible values.	
	"slot": "suppliers.show",	 
	# Some APIs require a bearer token, or a 2-step process, this is where you handle that.
	"before_data": {}, 
	"data": {
		"coupa_data": {
			# You can add context specific values to this API call, {{context.contract.supplier_name}} for example
			"uri": "http://fake.test", 
			# This works intuitively, just specify your API headers here, Bearer token, params, etc.
			"headers": {} 
		}
	},
	"blocks": [
		{
			"type": "number",
			# This is hard-coded title for this block, cant use api data, or contextual data here	
			"title": "Title for number block",
			# "coupa_data" was the API response above, .[0] returns the stuff in the {}, ".data_number" gets the value, 
			# in this case "42"
			"data": {
				"type": "jq",
				"jq": ".coupa_data | .[0] | .data_number"	
			}
		}, 
			# So this block renders a specially formatted number block, with the number "42" in large bold font, 
			# and a text label/title of "Title for number block"
		{
			# Fields block has some of the strictest requirements for data, It displays all data in key -> value pairs
			"type": "fields",
			"data": {
				"type": "jq",
				"jq": ".coupa_data | .[] | to_entries | map({ label: .key, value: .value })" 
			}
		},
		{
			# For this block, we are just going to pull the hash out from the [] and use the values inside it
			"type": "text",
			"data": {
				"type": "jq",
				"jq": " .coupa_data | .[0]"
			},
			# Text blocks gives you a lot of flexibility for displaying data from the API response in context.
			# The text can be formatted just like markup, so you can create links, tables, render/resize images, etc.	 
			"text": "{{ data_number }}	is the data_number" 
		},
		{
			# Setting up the bar graph is pretty tricky, maybe work with us if you want to go this route.
			# But this example creates a bar graph with values/labels bar sizes based on the values in the API response
			"type": "bar",
			"title": "Bar graph with fake data",
			"data": {
				"type": "jq",
				"jq": "[{name: \"Overall Score\", data: [.coupa_data | .[0].data_number]}, 
								{name: \"Environment score\", data: [.coupa_data | .[0].second_score]}]" 
			},
			"axes": {"xAxis": {"labels": { "enabled": false}}, "yAxis": {"title": { "text": ""}, "max": 100} }
		}
	]
}

パートナーのインスタンスでテスト

Coupaでこれをテストするには、バージョンR25.0以降である必要があります。 最終的に、アプリはApp Directoryの一部となり、カスタムPanelアプリにはなりませんが、Coupaが正式にアプリをApp Directoryに追加する前に、これらの手順を使用して自分でテストできます。

  1. [設定]に移動します。
  2. [プラットフォーム]で[インストール済みアプリ]をクリックします
  3. [作成]ボタンをクリックし、[新しいPanelアプリを作成]を選択します
  4. アプリを作成する
  5. 名前を追加
  6. 記述子セクションに、上記のコードを含めます

完了すると、エラーがない場合は、サプライヤーページごとにPanelアプリが表示されます。

このページに表示されている一部、または全ての内容は、機械翻訳によるものです。ご了承ください。

関連アイテム


Coupa Core API

RESTful APIは、Coupaプラットフォームでデータの読み取り、編集、統合を行うための堅牢なアクセスを提供します。

リソース

オブジェクトのタイプごとにAPIエンドポイントを整理しました。参照データ、トランザクションデータ、および共有リソース。

参照データリソース

リファレンスデータは、ユーザー、サプライヤー、アカウントなど、Coupaのコアコンポーネントを設定するために使用されます。

取引リソース

Coupaを使用すると、依頼書、発注書、請求書などのトランザクションデータが作成されます。