Create a Panel

Specifies the page type where the panel will be rendered. Current options are:

• user.home (Coupa homepage: / and /user/home )
• suppliers.show (supplier details page: /suppliers/:id/record )
• supplier_order_headers.show
• items.show (item details page: /items/{id} )
• contracts.show (contract details page: /contracts/show/:id )
• requisition_headers.edit (Coupa shopping cart: /requisition_headers/{id}/edit )
• invoices.show (invoice details pages, including editing invoices on the next gen invoicing UI: /invoices/{id} and /invoices/{id}/show_for_approval )
• receipts.full_receipt (Detailed receipt page: /receipts/{id}/full_receipt )
• expenses.index (Expenses landing page: /expenses )
• projects.show (project details page: /projects/{id} )
• quotes/requests.show (sourcing event details page: /quotes/requests/{id} )
• asn/headers.show (ASN details page: /asn/headers/{id} )
• asn/supplier_headers.show
• budget_lines.show (budget lines page: /budget_lines/{id})
• category_planner_categories.show (category profile page: /category_planner_categories/r#/categories/{id})

{
	 "slot": "user.home"
 }

Only one slot can be specified per panel app. To have the app appear on multiple pages, create the app again with the desired slot value.

data

The data attribute describes how to fetch the desired data that is rendered in the panel.  A JSON object that describes what data to fetch to render the panel. The values in this object will be URLs that Coupa will send a request to in order to retrieve data. The responses from all of these data requests will be merged into one Hash, aliased under the key name given to them in this object.

"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"
	}
}

Each slot provides contextual detail about the page on which it is displayed. For example a panel app being displayed on a supplier show page will have access to contextual data about that specific supplier. You can use this contextual information in your data objects, but not in blocks . So when a panel app renders on the show page for “ACME Supplier” the API call can be customized based on the supplier’s name, coupa ID, custom field values, and other properties of that supplier.

An API call to the NY Times article search for recent articles about a supplier would look like this:

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

Contact Coupa for an updated list of what contextual data is available for each slot.

Added at the beginning of the JSON body allows to configure the timeout for the panel's API response.

An example block would be:

{
	"timeout": 30,
	"properties": {
		"client": {
			"type": "string"
	}

An array of properties that a user/administrator has to furnish after enabling your panel app. If your app/API requires a unique API key, or login/password for each Coupa customer that enables it, here's how you provide that option.

An example block would be:

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

You then reference your properties in the data blocks like this:

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

When a Coupa admin enables a new panel app, they will be prompted to fill in all “properties” fields specified in your app descriptor.

Adds a Launch Button that can be used when a Panel App does not need to be displayed immediately. Rather than the Panel App automatically reaching out to the 3rd party and rendering the data, it only reaches out if the end user manually clicks the Launch Button.

This JSON object includes description , button_text and help_text . For example:

"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."
	}

How to use launch :

• Use if the data in the Panel App is only relevant for specific business cases within the page
• Add at the same level as slot , data , etc, but not in blocks

Adds a Refresh Button that can be used when data on the page changes and affects the data rendered in the Panel App. This is handy for your Cart Panel App when a Req line is updated. The user can click Refresh Button to update the data in the Panel App.

This is boolean option is used to display a refresh button on the Panel App in the app descriptor:

"allow_refresh": true

How to use allow_ refresh :

• Use if the data required by the app can be updated by the user and the app needs the new data

When clicked, the button refreshes the contents on that app. This field should be added on the same level as “slot”, “data”, “launch” etc, but not in blocks. The refresh button is shown at the top of panel application.

The blocks attribute describes how to render data in the panel. It is an array of JSON objects ("blocks") of various types that each describe a separate visualization. Blocks have access to the data that was previously sent and use it to create visualizations.

type

Identifies the type of block. For example, fields , text , or bars . This will determine how the block is rendered in the panel on the UI, and also the required format for the data.

data

This JSON object will have different properties depending on strategy.

JQ

• type must equal "jq"

• jq is a string that contains a JQ script. The JQ script is fed the merged data structure from the data attribute as its input and must produce a JSON structure that fits the required format for the block type.

Processing data with JQ

For example, the following JQ script could be used to extract several specific pieces of data and repackage them in another JSON object:

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

This would result in the following JSON object being produced:

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

More information:

• JQ 1.6 manual or JQ on GitHub

• ruby-jq gem on GitHub

other properties

Different blocks types may have other properties specific to that block type.

type

Must equal text

The text block type uses a Liquid Markdown template. The template is first parsed as Liquid to interpolate the data that's returned from the requests. Then, the template is parsed again as Markdown to generate the HTML.

Markdown provides a safe method of generating HTML, and for security reasons, Coupa blocks inline HTML in the template. There's no character limit other than the max limit of the data column that stores the block's configuration.

Markdown allows for headers, inline emphasis formatting, lists, images, links, and blockquotes. Coupa also supports syntax highlighting and tables.

For detailed info about working with Liquid and Markdown, see Liquid template language and Mastering Markdown .

The data strategy must produce a single JSON object. All of the keys in the object will be available to the Liquid template as variables.

{
	 "foo": "bar",
	 "fizz": {
			"buzz": "buzz"
	 }
}

type

Must equal field

The data strategy must produce an array of JSON objects with label and value attributes. When rendering, the label will be used as the field label and the value will be used as the field value.

[
	 {
			"label": "Foobar",
			"value": "fizzbuzz"
	 },
	 {
			"label": "Lorem Ipsum",
			"value": 42
	 }
]

type

Must equal bar or line

The data strategy must produce an array of arrays. Unlike the Table Block, the data for bar/line graphs will be column-oriented.

Each array represents a single series of data that will be displayed. The first element is the name of the series, then the remaining elements are the points in the series.

[{
		"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]
}]

type

Must equal pie

The data strategy must produce a column-oriented array of arrays as described in the Bar/Line Block section.

[{
		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
}]

type

Must equal money

• Amount a JSON Float to determine the amount of currency.
• Currency a string containing the ISO 4217 currency code of the currency.

{
	"amount": 42.0,
	"currency": "USD"
}

Type

Must equal numbers

The data strategy must produce a single JSON integer or Float.

42.0

"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": {
		"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 }}"
			}
		}
	}

invoice_id , invoice_date , invoice_number , supplier_name , supplier_number , supplier_id

id , name , display_name , duns , number , tax_id , website , status

custom_fields: object.supplier.custom_field_values_hash

id , event_name , event_commodity , project_id , supplier_id , and any custom fields and tags