Prerequisites<\/h2>\n\n\n\n
To follow along with this tutorial, you will need a good grasp of JavaScript ES6. You will also need to have an understanding of some basic React concepts like hooks and functional components.<\/p>\n\n\n\n
You will need to have these installed on your workstation:<\/p>\n\n\n\n
- An up-to-date installation of node.js<\/a>, and a package manager like npm<\/a> or yarn<\/a><\/li>
- Your preferred code editor<\/li>
- An API communicating with your CircleCI webhook. You can read about setting one up here<\/a>.<\/li>
- Ensure that the Laravel API CircleCI webhook<\/a> covered in this tutorial<\/a> is up and running.<\/li><\/ol>\n\n\n\n
Our tutorials are platform-agnostic, but use CircleCI as an example. If you don\u2019t have a CircleCI account, sign up for a free one here.<\/a><\/strong><\/p><\/blockquote>\n\n\n\n
Getting started<\/h2>\n\n\n\n
Create a new React application using this command:<\/a><\/p>\n\n\n\n
yarn create react-app circleci_workflow_dashboard\n\ncd circleci_workflow_dashboard\n<\/code><\/pre>\n\n\n\nFor this project, we will be using Ant Design<\/a> for laying out the UI and react-chartjs-2<\/a> to display our charts.<\/p>\n\n\n\n
Add the project dependencies using yarn:<\/a><\/p>\n\n\n\n
yarn add antd react-chartjs-2@3.3.0 chart.js\n<\/code><\/pre>\n\n\n\nThe next step is to import the styling for ant design. Update
src\/App.css<\/code> with this:<\/a><\/p>\n\n\n\n@import '~antd\/dist\/antd.css';\n<\/code><\/pre>\n\n\n\nAdding utility functionality<\/h2>\n\n\n\n
Next, we need a means of communicating with our API. In the
src<\/code> folder, create a new folder calledutility<\/code>. In theutility<\/code> folder, create a new file namedAPI.js<\/code>. In thesrc\/utility\/API.js<\/code> file, add this:<\/a><\/p>\n\n\n\nexport const makeGETRequest = (url) => {\n return fetch(url, {\n method: \"GET\",\n headers: {\n \"Content-Type\": \"application\/json\",\n },\n }).then((response) => response.json());\n};\n<\/code><\/pre>\n\n\n\nUsing this function, we can make a
GET<\/code> request to the API. The function returns the JSON response from the API.<\/p>\n\n\n\nFor the sake of simplicity, error handling is not included in the function.<\/p><\/blockquote>\n\n\n\n
To represent dates in a readable format, we can create a utility function. In the
utility<\/code> folder, create a new file calledDate.js<\/code> and add this:<\/a><\/p>\n\n\n\nexport const formatDate = (date) =>\n new Date(date).toLocaleString(\"en-GB\", {\n month: \"long\",\n weekday: \"long\",\n day: \"numeric\",\n year: \"numeric\",\n });\n<\/code><\/pre>\n\n\n\nBuilding dashboard components<\/h2>\n\n\n\n
Our dashboard will display a table of events you can filter on status and event type. You will also be able to toggle the dashboard between a tabular display and a chart display.<\/p>\n\n\n\n
In the
src<\/code> folder, create a new folder calledcomponents<\/code>. This folder will hold all the custom components we will create.<\/p>\n\n\n\nIn the
components<\/code> directory, create a new file calledStatusTag.jsx<\/code>. This component will be used to display a tag with a color determined by the event\u2019s status. Add this toStatusTag.jsx<\/code>:<\/a><\/p>\n\n\n\nimport React from \"react\";\nimport { Tag } from \"antd\";\n\nconst StatusTag = ({ status }) => {\n const statusColours = {\n success: \"green\",\n failed: \"volcano\",\n error: \"red\",\n canceled: \"orange\",\n unauthorized: \"magenta\",\n };\n return <Tag color={statusColours[status]}>{status}<\/Tag>;\n};\n\nexport default StatusTag;\n<\/code><\/pre>\n\n\n\nNext, create a new file in the
components<\/code> directory namedTableView.jsx<\/code>. This component will take the notifications as a prop and render them in a table with the ability to filter based on type and status. Add this code toTableView.jsx<\/code>:<\/a><\/p>\n\n\n\nimport React from \"react\";\nimport { Table } from \"antd\";\nimport { formatDate } from \"..\/utility\/Date\";\nimport StatusTag from \".\/StatusTag\";\n\nconst TableView = ({ notifications }) => {\n const filterHandler = (value, record, key) => record[key] === value;\n\n const columns = [\n {\n title: \"Subject\",\n dataIndex: \"commit_subject\",\n },\n {\n title: \"Commit Author\",\n dataIndex: \"commit_author\",\n },\n {\n title: \"Happened At\",\n dataIndex: \"happened_at\",\n render: (text) => formatDate(text),\n },\n {\n title: \"Event Type\",\n dataIndex: \"type\",\n filters: [\n { text: \"Job\", value: \"job-completed\" },\n { text: \"Workflow\", value: \"workflow-completed\" },\n ],\n onFilter: (value, record) => filterHandler(value, record, \"type\"),\n },\n {\n title: \"Event Status\",\n dataIndex: \"event_status\",\n filters: [\n { text: \"Success\", value: \"success\" },\n { text: \"Failed\", value: \"failed\" },\n { text: \"Error\", value: \"error\" },\n { text: \"Canceled\", value: \"canceled\" },\n { text: \"Unauthorized\", value: \"unauthorized\" },\n ],\n render: (text) => <StatusTag status={text} \/>,\n onFilter: (value, record) => filterHandler(value, record, \"event_status\"),\n },\n {\n title: \"Notification ID\",\n dataIndex: \"notification_id\",\n render: (text, record) => (\n <a href={record[\"workflow_url\"]} target=\"_blank\" rel=\"noreferrer\">\n {text}\n <\/a>\n ),\n },\n ];\n\n return (\n <Table dataSource={notifications} columns={columns} rowKey=\"id\" bordered \/>\n );\n};\n\nexport default TableView;\n<\/code><\/pre>\n\n\n\nThe table has six columns: Subject, Commit Author, Happened At, Event Type, Event Status, and Notification ID.<\/p>\n\n\n\n
Each column is represented by an object in the
columns<\/code> constant. Where no special rendering is required, thetitle<\/code> anddataIndex<\/code> are sufficient for the column declaration. Thetitle<\/code> is used as the title of the column while thedataIndex<\/code> entry lets antd know which property the column is populated with.<\/p>\n\n\n\nTo specify the component or JSX element to be rendered in a column, we add a
render<\/code> key to the column\u2019s object representation. We use this to render theStatusTag<\/code> component we created earlier. We also use this to render a well-formatted date for theHappened At<\/code> column and the Notification ID as a link to the workflow.<\/p>\n\n\n\nBuilding chart components<\/h2>\n\n\n\n
For this tutorial, we will render the data in three charts:<\/p>\n\n\n\n
- A pie chart showing the distribution of events by status: success, failed, error, canceled, or unauthorized.<\/li>
- A bar chart showing the distribution of events by type: either workflow or job<\/li>
- A line chart showing the timeline of events<\/li><\/ol>\n\n\n\n
To build the pie chart, create a new file in the
components<\/code> folder calledStatusDistribution.jsx<\/code> and add this code to it:<\/a><\/p>\n\n\n\nimport React from \"react\";\nimport { Pie } from \"react-chartjs-2\";\n\nconst StatusDistribution = ({ notifications }) => {\n const sortedNotifications = notifications.reduce(\n (sortedNotifications, notification) => {\n sortedNotifications[notification[\"event_status\"]]++;\n return sortedNotifications;\n },\n { error: 0, failed: 0, success: 0, unauthorized: 0, canceled: 0 }\n );\n\n const data = {\n labels: [\"Error\", \"Failed\", \"Success\", \"Unauthorized\", \"Canceled\"],\n datasets: [\n {\n data: Object.values(sortedNotifications),\n backgroundColor: [\n \"rgba(255, 99, 132, 0.2)\",\n \"rgba(255, 206, 86, 0.2)\",\n \"rgba(75, 192, 192, 0.2)\",\n \"rgba(153, 102, 255, 0.2)\",\n \"rgba(255, 159, 64, 0.2)\",\n ],\n borderColor: [\n \"rgba(255, 99, 132, 1)\",\n \"rgba(255, 206, 86, 1)\",\n \"rgba(75, 192, 192, 1)\",\n \"rgba(153, 102, 255, 1)\",\n \"rgba(255, 159, 64, 1)\",\n ],\n borderWidth: 1,\n },\n ],\n };\n\n return (\n <>\n <div className=\"header\">\n <h1 className=\"title\">Status Distribution<\/h1>\n <\/div>\n <Pie data={data} height={50} \/>\n <\/>\n );\n};\n\nexport default StatusDistribution;\n<\/code><\/pre>\n\n\n\nUsing the
reduce<\/code> function on the notifications array, the notifications are sorted and counted according to the status. The values are then passed to thedata<\/code> key in thedatasets<\/code> configuration, which is passed to thePie<\/code> component.<\/p>\n\n\n\nTo build the bar chart, create a new file in the
components<\/code> directory calledTypeDistribution.jsx<\/code> and add this code to it.<\/a><\/p>\n\n\n\nimport React from \"react\";\nimport { Bar } from \"react-chartjs-2\";\n\nconst TypeDistribution = ({ notifications }) => {\n const sortedNotifications = notifications.reduce(\n (sortedNotifications, notification) => {\n sortedNotifications[notification[\"type\"]]++;\n return sortedNotifications;\n },\n { \"job-completed\": 0, \"workflow-completed\": 0 }\n );\n\n const data = {\n labels: [\"Job\", \"Workflow\"],\n datasets: [\n {\n label: \"Event Type\",\n data: Object.values(sortedNotifications),\n backgroundColor: [\"rgba(54, 162, 235, 0.2)\", \"rgba(75, 192, 192, 0.2)\"],\n borderColor: [\"rgba(54, 162, 235, 1)\", \"rgba(75, 192, 192, 1)\"],\n borderWidth: 1,\n },\n ],\n };\n\n const options = {\n scales: {\n y: {\n beginAtZero: true,\n },\n },\n };\n\n return (\n <>\n <div className=\"header\">\n <h1 className=\"title\">Type Distribution<\/h1>\n <\/div>\n <Bar data={data} options={options} height={500} \/>\n <\/>\n );\n};\n\nexport default TypeDistribution;\n<\/code><\/pre>\n\n\n\nJust as we did for the status distribution chart, we sort and count the notifications based on the notification type. The values are then passed to the
data<\/code> key in thedatasets<\/code> configuration, which is passed to theBar<\/code> component.<\/p>\n\n\n\nTo build the timeline of notifications, create a new file in the
components<\/code> directory calledTimeline.jsx<\/code> and add this code to it:<\/a><\/p>\n\n\n\nimport React from \"react\";\nimport { Line } from \"react-chartjs-2\";\nimport { formatDate } from \"..\/utility\/Date\";\n\nconst Timeline = ({ notifications }) => {\n const sortedNotifications = notifications.reduce(\n (sortedNotifications, notification) => {\n const notificationDate = formatDate(notification[\"happened_at\"]);\n if (notificationDate in sortedNotifications) {\n sortedNotifications[notificationDate]++;\n } else {\n sortedNotifications[notificationDate] = 1;\n }\n return sortedNotifications;\n },\n {}\n );\n\n const data = {\n labels: Object.keys(sortedNotifications),\n datasets: [\n {\n label: \"Number of events\",\n data: Object.values(sortedNotifications),\n fill: false,\n backgroundColor: \"rgb(255, 99, 132)\",\n borderColor: \"rgba(255, 99, 132, 0.2)\",\n },\n ],\n };\n\n const options = {\n scales: {\n y: {\n beginAtZero: true,\n },\n },\n };\n return (\n <>\n <div className=\"header\">\n <h1 className=\"title\">Event Timeline<\/h1>\n <\/div>\n <Line data={data} options={options} height={500} width={1500} \/>\n <\/>\n );\n};\n\nexport default Timeline;\n<\/code><\/pre>\n\n\n\nThe sorting functionality for this component is slightly different. Because we cannot specify all the possible dates in an initial object, we start with an empty object. Then, for each notification, we check if a key already exists for that date. If it does, we increase the count, if not we add the date with a value of 1.<\/p>\n\n\n\n
Next, we need to build a component that renders all the charts in a grid. Create a new file in the
components<\/code> directory calledChartView.jsx<\/code> and add this code to it:<\/a><\/p>\n\n\n\nimport React from \"react\";\nimport StatusDistribution from \".\/StatusDistribution\";\nimport { Col, Row } from \"antd\";\nimport TypeDistribution from \".\/TypeDistribution\";\nimport Timeline from \".\/Timeline\";\n\nconst ChartView = ({ notifications }) => {\n return (\n <>\n <Timeline notifications={notifications} \/>\n <Row style={{ marginTop: \"30px\" }} gutter={96}>\n <Col>\n <StatusDistribution notifications={notifications} \/>\n <\/Col>\n <Col offset={6}>\n <TypeDistribution notifications={notifications} \/>\n <\/Col>\n <\/Row>\n <\/>\n );\n};\n\nexport default ChartView;\n<\/code><\/pre>\n\n\n\nIn this component, we render the status distribution and type distribution side-by-side with the timeline above.<\/p>\n\n\n\n
Passing the notifications as we have done here is known as prop drilling<\/a>. Although it is generally discouraged. we did it here for the sake of simplifying the tutorial. In production apps, you should consider a proper state management implementation.<\/p>\n\n\n\n
Putting it all together<\/h2>\n\n\n\n
With all the child components in place, update
src\/App.js<\/code> to match this:<\/a><\/p>\n\n\n\nimport \".\/App.css\";\nimport { makeGETRequest } from \".\/utility\/Api\";\nimport { useEffect, useState } from \"react\";\nimport { Card, Col, Row, Switch } from \"antd\";\nimport TableView from \".\/components\/TableView\";\nimport ChartView from \".\/components\/ChartView\";\n\nconst App = () => {\n const [notifications, setNotifications] = useState([]);\n const [showTableView, setShowTableView] = useState(false);\n\n useEffect(() => {\n makeGETRequest(\"http:\/\/127.0.0.1:8000\/api\/circleci\").then((response) => {\n setNotifications(response);\n console.log(response);\n });\n }, []);\n\n const handleSwitchValueChange = () => {\n setShowTableView((showTableView) => !showTableView);\n };\n\n return (\n <Card style={{ margin: \"2%\" }}>\n <Row style={{ marginBottom: \"10px\" }}>\n <Col span={6} offset={18}>\n Show Data as Table\n <Switch checked={showTableView} onChange={handleSwitchValueChange} \/>\n <\/Col>\n <\/Row>\n {showTableView ? (\n <TableView notifications={notifications} \/>\n ) : (\n <ChartView notifications={notifications} \/>\n )}\n <\/Card>\n );\n};\n\nexport default App;\n<\/code><\/pre>\n\n\n\nIn this component, we retrieve the notifications from our API in the
useEffect<\/code> hook and save it to state using thesetNotifications<\/code> function. We then declare a function to handle the toggling of theshowTableView<\/code> state variable, which determines whether the data is displayed in a table or chart.<\/p>\n\n\n\nTo toggle between views, we render a
Switch<\/code> and pass it theshowTableView<\/code> andhandleSwitchValueChange<\/code> values as props.<\/p>\n\n\n\nFinally, depending on the value of
showTableView<\/code>, either theTableView<\/code> orChartView<\/code> component is rendered.<\/p>\n\n\n\nTable view<\/h3>\n\n\n\n
![\"Dashboard](\"https:\/\/production-cci-com.imgix.net\/blog\/media\/2022-01-07-react-dashboard.png?ixlib=rb-3.2.1&w=2000&auto=format&fit=max&q=60&ch=DPR%2CWidth%2CViewport-Width%2CSave-Data\")
<\/figure>\n\n\n\nChart view<\/h3>\n\n\n\n
![\"Dashboard](\"https:\/\/production-cci-com.imgix.net\/blog\/media\/2022-01-07-table-view.png?ixlib=rb-3.2.1&w=2000&auto=format&fit=max&q=60&ch=DPR%2CWidth%2CViewport-Width%2CSave-Data\")
<\/figure>\n\n\n\nConclusion<\/h2>\n\n\n\n
In this tutorial, we examined how we can build a React dashboard to visualize pipeline events using an API. By visualizing data in charts, we can get a high-level understanding of our pipeline and also make sense of the dataset, no matter how large. While we did not implement this feature, you can also export the data into spreadsheets for further analysis. Share this sample project with your team and extend your learning!<\/p>\n\n\n\n
The code for this article is available on GitHub<\/a> and the complete documentation for CircleCI webhooks is available here<\/a>.<\/p>\n\n\n\n
\n\n\n\n