Adapter build concepts

Custom adapters are created based on the data source, the format of the incoming data, and the proprietary logic written in the code. They include various elements configured together to deliver data to and publish data from the adapter. These elements include a task payload, APIs, and a data source type schema — all of which can be configured in a number of combinations.

Basic adapter sequence

The basic adapter sequence starts with the system creating a new job with an ingestion task targeted at the adapter.

Then, the adapter needs to handle:

1. The adapter receives a JSON payload with task details
2. The adapter instance calls the external system and coordinates the data collection task.
3. The adapter acquires the raw data from the input source and generates output according to its objectives (stream, chunk, or raw format).

If building a custom adapter, each step in this sequence must be built into your code.

If the output of an adapter is a stream audio or video for downstream tasks, the best format is ffmpeg nut container. This helps ensure consumers of the stream (especially tasks with engines using ffmpeg to segment the stream further) are able to access it.

In the GraphQL API, adapters are identified as engines where EngineType=Ingestion.

Source type and schema

An adapter references a source type and contains a schema that describes the structure for incoming data. A source type might be audio, YouTube content, a Dropbox file, or a podcast, for example. A full list of supported source types is in the table below.

Together, a source type and schema define a set of fields that can be queried. When your adapter runs, it runs against the schema of the Source Type ID received in the task payload.

Your adapter must specify what source type(s) it supports by declaring an array of source type IDs in the manifest file:

A list of source types can be retrieved by calling the getSourceTypes query.

query getSourceTypes {
  sourceTypes {
    records {
      id
      name
    }
  }
}

The source types currently supported are:

query getSourceType {
  sourceType(id: 6) {
    name
    sourceSchema {
      id
      validActions
      definition
    }
    organizationId
  }
}

[Note] Although a schema cannot be modified, you can add a subset of custom fields to the query.

Payload

Upon execution, your adapter receives a task payload that includes the source ID for ingestion.

Input and output models

When constructing your adapter, specific data fields must be used to define the inputs to and outputs from your service. Each adapter type has supported data types and required fields, and there are advanced options you can set to control other aspects of how data is delivered to its defined output.

Deployment models

Adapters can be deployed in ways that can satisfy security and compliance requirements, if needed. In most cases, adapters will be deployed for external access.

• Network isolated deployment: the adapter performs within its container and does not send user data off the container.
• External access deployment: the adapter requires internet access for tasks such as license checks, database updates, and retrieving the ingestion data.

Compliance testing

Each build that is uploaded to Veritone is required to undergo compliance testing to ensure it works securely and meets the needs of Veritone's customers. Part of this testing includes a vulnerability scan of the Docker image to detect security issues and potential vulnerabilities. A build must pass the compliance testing before it can be deployed to production in Veritone. If security issues are found, a report that details the results of the testing is provided to give insight as to why the build did not pass.

Adapter states

aiWARE uses adapter states to capture the most relevant aspects of an adapter's lifecycle and operations and to help you easily identify and track your adapter's progression through the development workflow.

There are four available states for adapters, three of which apply to workflow stages. Workflow-related states are automatically set by the system and transition from one to the next when certain functions are carried out.

1. Upon registration, an adapter enters the Pending state.
2. From there, the adapter progresses to Ready when a build is approved.
3. The adapter becomes Active when it's live in the Veritone platform.
4. The final non-workflow state allows you to manually disable an adapter and stop it from processing new tasks.

The table below provides additional information about each of the adapter states, including details about transitions and optional actions that can be performed.

Build states

The build state allows you to easily identify and track a build's progression through the workflow cycle. Veritone uses seven different states to capture the most relevant aspects of a build's lifecycle stages and general operations.

The build approach

In the Resource Center utility, the term adapter is used to reference the external-facing, user-friendly representation of your software. You can build an adapter to ingest data from an external source that's not already supported and upload to Resource Center as a resource.

The actual code and processing algorithms are contained in a build. A single adapter can contain multiple builds, but only one build can be deployed in production at a time. The adapter and build approach allows you to update, test, and refine your code while offering the latest version of your adapter to the marketplace. Once a new build is approved, it can be deployed to production and replace the existing one.

• Create an IO adapter
• Writing engines
• For outputs that are streams of audio or video, use the ffmpeg nut container. See https://ffmpeg.org/nut.html
• See an overview of adapters
• Veritone's out-of-the-box adapters

• Developer's reference
• Engines
• Writing engines
• Adapter build concepts

• Basic adapter sequence
• Source type and schema
• Payload
• Input and output models
• Deployment models
• Compliance testing
• Adapter states
• The build approach