Skip to main content

Initializing a New Component

Initializing a new connector​

To initialize a new project, run prism components:init {{ CONNECTOR NAME }}. If you do not have Prismatic's CLI tool, prism, installed, please take a moment to look through the Prism overview page.

prism components:init acme-erp

Your component name must be comprised of alphanumeric characters, hyphens, and underscores, and start and end with alphanumeric characters. You will be prompted with a couple of questions - to give a description for your component and to determine what connection authorization type should be templated (you can edit those later).

This will create a directory structure that looks like this:

acme-erp
├── assets
│   └── icon.png
├── jest.config.js
├── package.json
├── src
│   ├── actions.ts
│   ├── client.ts
│   ├── connections.ts
│   ├── index.test.ts
│   ├── index.ts
│   └── triggers.ts
├── tsconfig.json
└── webpack.config.js
  • assets/icon.png is the icon that will be displayed next to your component. Square transparent PNGs at least 128 x 128 pixels in size look best, and will be scaled by the web app appropriately.
  • jest.config.js contains configuration for the Jest testing framework.
  • package.json is a standard node package definition file.
  • src/actions.ts contains your component's actions. This can be broken out in to distinct files as your code grows.
  • src/client.ts contains a shared "client". This is handy for actions that share a mechanism for connecting to an API. The "client" will probably be an authenticated HTTP client that's configured to make requests of a particular endpoint.
  • src/connections.ts contains the connections that your component uses to authenticate with third-party APIs.
  • src/index.test.ts contains tests for component's actions. See Unit Testing Custom Components.
  • src/index.ts contains your component definition.
  • src/triggers.ts contains custom triggers.
  • tsconfig.json contains configuration for TypeScript.
  • webpack.config.js contains configuration for Webpack.

Custom connectors from WSDLs or OpenAPI specs​

Third-party apps and services often provide APIs with hundreds of RESTful endpoints. It would be tedious to manually write actions for each individual endpoint. Luckily, many companies also provide an API specification - commonly a Web Service Definition Language (WSDL) file, or an OpenAPI (Swagger) specification.

You can generate a custom component from a WSDL file with prism by passing the --wsdl-path flag to the components:init subcommand:

prism components:init myThirdPartyComponent --wsdl-path ./thirdPartySpec.wsdl

You can generate a custom component from an OpenAPI definition (you can use a YAML or JSON file - both work fine) with prism by passing the --open-api-path flag to the components:init subcommand:

prism components:init myThirdPartyComponent --open-api-path ./third-party-openapi-spec.json

The custom component code that is generated may require some tweaking - some APIs have undocumented required headers, or irregular authentication schemes (so you may need to touch up src/client.ts or src/connection.ts). But, this does give you a great jumping-off point when building a custom component for a third-party app.