Oh VCs – How do I stage thee? Let me count the ways

Credential Master provides a wide range of tools for managing the lifecycle of VCs. This blog post looks at the staging tools in detail.

 Introduction to Staging

In the real world of managing and issuing VCs, staging is a critical process.

Staging is the process of building the “potential credential” — populating the attribute values from source data — prior to offering it to the Holder.

As the contents of VCs are used as the basis of some level of trust in ecosystems other than from where they were issued, it is rather important that the values placed in each attribute of the VC are accurate. 

With Credential Master, the staging process aims to meet certain key requirements:

  • It should be wherever possible, driven by configuration, rather than by writing code
  • It should be fully automatic — if 1,000 VCs are to be offered, once the process is initiated, staging should require no human interaction
  • It should read source data value directly from the system of record for each attribute
  • It should be just-in-time, reading the source data from the system of record immediately before offering the VC

The rest of this blog post explains how Credential Master meets these requirements.

Configuring Schemas and Credential Definitions

Before a VC can be offered, a Credential Definition must be configured, which specifies the attributes (data values) that will populate the VC.

Credential Definitions are based on Schemas, which are configured first.

Preset values in the Schema

It’s right here that you can start providing values for attributes, because for some Schemas, an attribute may have a preset value — for example, configuring a Schema for a Bachelor’s Degree issued by your University, the “Conferred By” attribute may always have a value of “The University of San Francisco School of Medicine”.

Here’s what a such a Schema attribute definition looks like:

With Credential Master, each attribute definition lets you choose a Type — Text, Date, Number, etc. — and you can also set a fixed value for each type — Text Value, Number Value, etc.

That’s it — the credential attribute “Conferred By” will by default have a value of “The University of San Francisco School of Medicine”.

Preset values in the Credential Definition

As previously mentioned, Credential Definitions are based on Schemas.

When you create a Credential Definition, you specify the Schema that it is based on.  

Credential Master copies of the attribute records for that Schema to the new Credential Definition, which of course means that the Type and any preset values are also copied.

Now you can just leave the attribute records as they are, or you can modify them, effectively overriding their Schema values.

So, if a Schema attribute has no preset value, you can add the preset value at the Credential Definition stage, otherwise you can override the Schema value.

Also note that you can delete attribute records in the Credential Definition, effectively making it a subset of the Schema.

Populating attribute values from “in-context” source objects

As you may know, Credential Master runs on the Salesforce platform.  This makes a wide range of data objects available to Credential Master as data sources during staging.

And if your business is using Salesforce, you will have added custom objects specific to your business, so those custom objects are also available as data sources.

Let’s look at how we can populate attribute values from data objects in the Salesforce database, or other systems of record.

The process of run-time staging of a VC in Credential Master first starts with the creation of a Credential record in the Salesforce database.

Here is a subset of the Credential Master data model:

As you can see from this, the Credential object is at the bottom of a hierarchy of objects.

So for a specific Credential object instance, there are instances of the other objects above the Credential which can be considered to be “in-context” — available to use as source data objects.

This allows you at configuration time to choose a value for any attribute, from any data field in any of those objects.

For example, the standard Salesforce Contact object includes data fields for Firstname, Lastname, Birthdate, and so on.

To use the Contact Firstname field as an attribute source, in the Credential Definition attribute record, you simply set the Source Object to “Contact”, and the Source Field to “Firstname”:

To use the Contact Birthdate field as an attribute source, in the Credential Definition attribute record you simply set the Source Object to “Contact”, and the Source Field to “Birthdate”, and also remember to set the Type to “Date”:

NOTE: even though all VC attributes are (currently) stored in wallets as text values, Credential Master allows you to specify the type of the data source, and it will automatically convert (e.g.) Date values in the source data to an equivalent text value for the wallet.

Populating attribute values from “out-of-context” source objects

So far so good, but the in-context objects represent a small subset of all of the possible data sources that we might want to use.

Within the Salesforce database, there are many data objects we may want to use, and even more in other external databases.

For any out-of-context data source, whether within the Salesforce database or external to it, provided we can specify a key field in one of the in-context objects that can be used to identify a record in that out-of-context data source, Credential Master can stage an attribute value at run time.

For example, let’s say there is a custom object in the Salesforce database called Credit Score, a parent of the Contact object, but clearly not one of the in-context objects.

Because we can get to the Credit Score object instance for a specific Contact by following the lookup field vcms__Credit_Score__c, we can configure a Credential Definition attribute to specify this, as follows:

Credential Master run-time staging finds the out-of-context object instance by using the context field and the source object key field, and makes all data fields in the out-of-context object instance available to the staging process, in the same way as it does for in-context objects.

Data sources external to Salesforce

So, what about data sources external to Salesforce?

Let’s use as an example the California Immunization Registry, a state-managed database containing immunization records for California residents – see https://cairweb.org.

Salesforce allows us to configure an External Object, wired to an External Data Source, which makes an external data table such as the California Immunization Registry table visible (read-only) to Credential Master as if it were a regular object in the Salesforce database:

The External Data Source component tells the system how to authenticate to and access the external database, and this can be achieved in several ways – by using the OData standard (see https://www.odata.org) if the external database supports it, or by calling a custom REST API on the external system.

The end result is that we can configure Credential Definition attributes to map to any field in the external database, by treating the External Object like any other out-of-context object:

Credential Master runtime staging finds the external object instance by using the context field and the source object key field, and makes all data fields in the external object instance available to the staging process in the same way as it does for in-context objects.

This way, you can ensure that you are always staging from the system of record for any attribute, regardless of where that data is held.

Build your own VC

Occasionally, a requirement for a VC will come along where none of the above Credential Definition configuration methods seems to apply; maybe the attribute data for the VC is generated dynamically — for example, when issuing a VC that contains an individual’s current temperature, which is generated by a temperature scanner and not recorded in any database, or maybe one of the attribute values needs to be an array of values from some child record.

To achieve this, you create a Credential Definition as usual, define the attributes (just the names and data types only), and specify in the Stager Class field the name of an Apex class written specifically to generate the body of the Credential — the list of attributes and values as a JSON string.

The Apex class must implement a method generateJSON, which does whatever is necessary to generate a JSON string with the required attributes and values — here’s an example where the entitlements attribute is an array of values:

Your generateJSON method is assisted by being called during run-time staging with the following parameters:

  • The name of the Processor being used (in case it has specific format requirements)
  • The Credential Definition (with attributes) being used
  • A map containing all of the in-context object instances, with all of their field values.

So as you can see, there’s a lot of context for your code to work from.

The generated JSON is saved in the JSON Attributes field of the Credential being staged, and overrides any attribute definitions.

Using the Credential Master REST API for Applications

Finally, for applications which are executing outside of the Salesforce platform, Credential Master provides a REST API which enables such external applications to issue and verify VCs.

Specifically, the REST POST /credentials service allows the application to create and offer a VC, complete with attributes.

There are two ways to provide the attribute values.

By providing each attribute separately:

By providing a single JsonAttributes value:

Summary

Let’s reiterate the key requirements for staging VCs:

  • It should be wherever possible, driven by configuration, rather than by writing code
  • It should be fully automatic — if 1,000 VCs are to be offered, once the process is initiated, staging should require no human interaction
  • It should read source data value directly from the system of record for each attribute
  • It should be just-in-time, reading the source data from the system of record immediately before offering the VC

We hope you can see that the powerful staging tools that Credential Master provides enables your business to meet all of these requirements, whether you are issuing 10 VCs, or millions. 

 

For more information, or if you have any questions about, or comments on this blog post, please use our Contact Form.

Alan Davies

June 2021

Share this post

Share on facebook
Share on google
Share on twitter
Share on linkedin
Share on pinterest
Share on print
Share on email