Appearance

Getting Started ​

Let's create a first, simple application for CatalogIQ - Hello World!

Prerequisites ​

In order to start you need to have access to CatalogIQ Admin and a CatalogIQ instance as a user. You will also need to have npm installed on your machine.

Create a new application ​

Let's start by creating a new application. We will create a simple "Hello World" application that will display a greeting.

  1. Create a new directory for the application:
bash
mkdir hello-world
cd hello-world
  1. Create a new file index.html with the following content:
html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Hello World</title>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>
  1. Create a new application manifest file app.json with the following content:
json
{
  "type": "web",
  "name": "hello-world",
  "display_name": "Hello World",
  "description": "Simple Hello World application",
  "icon": "far fa-hand-wave",
  "version": "1.0.0"
}
  1. Create a new API key in CatalogIQ Admin:
    1. Log in to CatalogIQ Admin
    2. Click on your user avatar in bottom left corner of the page
    3. Click on "Dev settings"
    4. Click on "Create new API Key"
    5. Enter the name of the key, e.g. "Hello World Deployment Key"
    6. Select key expiration date
    7. Click "Create"
    8. Copy the key and save it some place safe

WARNING

Remember to never commit your tokens to a git repository or store them in a public place. Remember to rotate your keys regularly and never share them with anyone. In case you suspect that your key has been compromised, revoke it immediately. If you use the key in CI/CD pipelines, make sure to store it securely as a secret.

  1. Zip the application files:
bash
zip -r app.zip .
  1. Upload the application to CatalogIQ substituting ${PITCHER_API_KEY} with the API key you created in step 4 and ${PITCHER_DOMAIN} with the domain of your CatalogIQ instance:
bash
  curl -X POST \
    -H "X-API-Key: ${PITCHER_API_KEY}" \
    -H "charts-Type: multipart/form-data" \
    -F "file=@app.zip" \
    https://${PITCHER_DOMAIN}.my.pitcher.com/api/v1/apps/publish/

INFO

You can also use use the REST API documentation to upload the application through a web page.

  1. Open CatalogIQ Admin, select your instance and navigate to the "Marketplace" inside the "Apps" section. You should see the "Hello World" application in the list. Click on "Install app" to install the application on the instance.

  2. Open CatalogIQ, you should see the hand icon in the left sidebar. Click on it to open the "Hello World" application. You should see the "Hello World!" message displayed.

  3. Now, let's make the app a little bit more dynamic. We will display a greeting with the username of the user. First add a script tag referencing @pitcher/js-api package to the index.html file. Then, add a script tag with the following code to the index.html file:

html
<script src="https://cdn.jsdelivr.net/npm/@pitcher/js-api"></script>
<script>
window.addEventListener('load', () => {
  window.pitcher.usePitcherApi().getEnv().then(env => {
   document.querySelector('h1').innerHTML = `Hello, ${env.pitcher.user.first_name} ${env.pitcher.user.last_name}`
  })
})
</script>

INFO

In a more complex setup you can install the @pitcher/js-api package using npm and bundle it with your application using a bundler like Webpack or Rollup.

  1. Now, increase the version number in app.json - every app release must have a unique version number. Zip the application files again and upload the new version to CatalogIQ using the same commands as in previous steps.
  2. Open CatalogIQ Admin and navigate to the "Apps" section. Hello World should be available in the list of installed apps. Click on the green "Update app" button to update the app to the new version.
  3. Open CatalogIQ and navigate to the "Hello World" app. You should see a greeting with your name displayed.
  4. Congratulations! You have created your first application for CatalogIQ!