Hypersync apps expose data from external services through proof types. For example, a Hypersync app for a user directory service might expose the following proof types:
- List of Users
- List of Groups
- Group Membership
Each proof type retrieves the relevant data from the external service and formats it appropriately for that data type. Data can be formatted in tabular, stacked and hierarchical layouts.
When a user selects a proof type, they may be prompted to provide criteria values. For example, the Group Membership proof type might require a group name to filter results. The criteria provider defines how these inputs are displayed and handled (e.g. as a text field or select control).
Proof types retrieve data from the app’s data source by name and can pass parameters to ensure the correct data is returned.
Tips for planning your proof types and fields
- Define different kinds of proof, such as Users, Groups, etc.
- Define key fields of information needed in each proof type. Ensure your API calls can return these vital elements.
- Define how to identify the right resource(s). This information can be unique to each proof type and is needed to configure
criteriafields.json. You should prompt the user for these values when they configure the Hypersync. For example, if your app connects to Azure, you may need to collect details such as the tenant ID, subscription ID, and resource group.
If you're having trouble finding this information, try the following:
- Check the service’s console or dashboard. These typically display all key configuration details by default and are a good place to start.
- Review similar proof types in other Hypersync apps for examples of how data and configurations are defined.
- Include user and permission data whenever possible.
Proof data can be formatted in the following ways:
| Layout | Description |
|---|---|
| Tabular | Data is arranged in a table where each row is an item in the data set. |
| Stacked | Fields in an item are arranged verticially, and that vertical stack is repeated for every row in the result set. |
| Hierarchical | A combination of tabular and/or stacked layouts where some layouts are nested. |
Tabular and stacked layouts can be exported as either PDF or Excel files, while hierarchical layouts currently support PDF output only.
Tabular and stacked layouts can also be defined declaratively using JSON files, whereas hierarchical proof types must be implemented in code.
Note: It's strongly recommended to avoid nested layouts.
Note: If you use control testing, or want to view proof as an Excel file, stick with a simple layout. No-code proof types only support simple layouts.
The Hypersync SDK allows you to define most common proof types declaratively using JSON files. Because these files are easy to read and modify, this no-code approach is recommended over writing TypeScript or JavaScript code for defining proof types.
Proof type JSON files are stored in the /json/proof directory, with one JSON file per proof type. To learn more about the JSON format, see the Proof Type JSON article or review the examples in the Hypersync SDK Samples repository.
The /json/proofTypes.json file lists the proof types currently exposed by your application. Any proof type JSON files present in your project but not listed in proofTypes.json remain hidden from users. This allows you to develop and test new proof types without exposing them until they’re ready for release. See the Proof Types JSON article for more information.
For proof types that are hierarchical or have other features that don't align with the no-code approach, the SDK makes it possible to author proof types in code.
When using code, each proof type is represented as a "proof provider" component. These components derive from the SDK's ProofProviderBase:
export class MyProofProvider extends ProofProviderBase {
async generateCriteriaMetadata(
criteriaValues: HypersyncCriteria,
pages: ICriteriaPage[]
): Promise<ICriteriaMetadata> {
// TODO: Generate the metadata for the criteria that are shown
// to the user when configuring this proof type. Will generally
// defer to a class that implements ICriteriaProvider.
}
async generateSchema(
criteriaValues: HypersyncCriteria
): Promise<IHypersyncSchema> {
// TODO: Generate the schema for the proof type. This schema information
// is used by Hyperproof's automated testing feature.
}
async getProofData(
hypersync: IHypersync,
hyperproofUser: IHyperproofUser,
authorizedUser: string,
syncStartDate: Date,
page?: string,
metadata?: SyncMetadata
): Promise<IGetProofDataResponse | IProofFile[]> {
// TODO: Fetch the data from the service and format it.
}
}Custom proof provider classes should live in the proof-providers directory in your package. There should also be an index file (i.e. index.ts or index.js) that exports each of the proof provider classes.
Example
Below is a index.ts example:
export * from './ListOfUsers';
export * from './ListOfGroups';
export * from './GroupMembership';