Registry Assistant Handbook

Overview

The Credential Engine offers the Registry Assistant API as a way to streamline publishing to the Credential Registry. The Registry Assistant uses a simplified version of the CTDL schema designed to be easy to map your data to. This guide is a step-by-step walkthrough for using the Registry Assistant API.

To use the Registry Assistant API, you will need:

  • A Credential Engine Account, including an Organization account that has been approved to publish via the Registry Assistant API
  • Your API key (obtainable via your Credential Engine Account)
  • A working knowledge of CTDL and related concepts
  • Programmatic read/write access to your data to generate and store CTIDs and retrieve the data for publishing
  • The ability to update your website or system to publish data to the Registry

Overview Presentation

Working Knowledge

This guide assumes a working knowledge of:

Additionally, it is recommended to be familiar with:

Getting your API Key

In order to publish/consume data using the Registry Assistant API, you will need an API Key. This key is connected to your organization in the Credential Engine Accounts site. If you do not already have an account and/or an approved organization:

  1. Navigate to the Credential Engine Accounts site.
  2. Create an account. After registering, you will receive an email to confirm your account.
  3. After confirming your account, you can add your organization.
  4. Complete the required information for the organization, along with publishing roles and methods, and submit the organization for approval.

A member of the CE team will review the organization request. Upon approval, an API key will be generated for your organization's account. This API key will be used for publishing and consuming (Note: You will not need the API key for requests to the Format endpoint).

Your organization's CTID and API key will be available on the organization dashboard on the accounts site, as shown below:

The organization CTID and API key can be found on the organization dashboard.

Managing your CTIDs

The CTID serves as the primary, unique identifier for all major objects in the Credential Registry. As such, it is critical that your system is able to associate each credential with its CTID, as this is the only way to update or delete the credential's data once it is published to the Registry.

CTIDs can be easily generated by concatenating ce- and a UUID or GUID. For example:

ce-fabac3e1-ba70-43b6-b0ce-5ff6108c8e7d

Most programming languages have methods to create a GUID.

  • Microsoft C#
    var myCTID = "ce-" + Guid.NewGuid().ToString().ToLower();
  • Java
    import java.util.UUID; var myCTID = "ce-" + UUID.randomUUID().ToString().ToLower();
  • SQL Server
    declare @Ctid varchar(50) set @Ctid = 'ce-' + Lower(convert(varchar(50),newID()))

API and Registry Features

This section describes features of the API and the environments to which you can publish.

Publishing Environments

The Credential Engine maintains two environments for publishing:

  • The sandbox environment, for testing your system and your data
  • The production environment, for real data

Sandbox

The Credential Engine offers a sandbox environment for both initial testing of publishing an organization's data and to allow feedback from CE on the range and type of data published. The sandbox should be used for all initial testing. An API key is normally not required for publishing to the sandbox. A partner who anticipates acting as a third party publisher may wish to use the sandbox environment to better understand the workflow. In this case, the CE team will work with the partner to simulate an environment in the sandbox similar to the anticipated workflow in production, including the use of API keys and identifying the CTIDs for 'client' organizations. The pattern for the sandbox URLs are as follows:

Format Data (no publishing)

https://sandbox.credentialengine.org/assistant/{CTDL object type}/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/{CTDL object type}/publish

Delete Data

https://sandbox.credentialengine.org/assistant/{CTDL object type}/delete

The majority of the code samples in this section will use the sandbox URLs.

Production

The production environment, naturally, is used to publish data to the production registry. Typically an organization will be required to use the sandbox environment first to validate how their data is retrieved, and formatted for publishing. The pattern for the sandbox URLs are as follows:

Format Data (no publishing)

https://apps.credentialengine.org/assistant/{CTDL object type}/format

Publish Data (automatically formats first)

https://apps.credentialengine.org/assistant/{CTDL object type}/publish

Delete Data

https://apps.credentialengine.org/assistant/{CTDL object type}/delete

Services

The Registry Assistant API provides three main services related to the credential registry:

  • Formatting your data in CTDL JSON-LD
  • Publishing your data in the Credential Registry
  • Deleting your data from the Credential Registry

Request/Response

Request

The Publish and Format endpoints use an HTTP POST request. Each endpoint type will have a custom input class. The input object will be provided in the body of the Post request.

Response

Response class returned from publish endpoints.

NOTE: If the document being published has the same contents as the currently published one, the envelope last updated_at date on the envelope will NOT be updated. As well a warning message will be returned.

/// <summary> /// Registry Assistant Response /// </summary> public class RegistryAssistantResponse { public RegistryAssistantResponse() { Messages = new List<string>(); Payload = ""; } /// True if action was successfull, otherwise false public bool Successful { get; set; } /// <summary> /// List of error or warning messages /// </summary> public List<string> Messages { get; set; } public string CTID { get; set; } /// <summary> /// URL for the registry envelope that contains the document just add/updated /// </summary> public string EnvelopeUrl { get; set; } /// <summary> /// URL for the graph endpoint for the document just add/updated /// </summary> public string GraphUrl { get; set; } /// <summary> /// Credential Finder Detail Page URL for the document just published (within 30 minutes of publishing) /// </summary> public string CredentialFinderUrl { get; set; } /// <summary> /// Identifier for the registry envelope that contains the document just add/updated /// </summary> public string RegistryEnvelopeIdentifier { get; set; } /// <summary> /// Payload of request to registry, containing properties formatted as CTDL - JSON-LD /// </summary> public string Payload { get; set; } }

Response class returned from format endpoints.

public class RegistryAssistantFormatResponse { public RegistryAssistantFormatResponse() { Messages = new List<string>(); Payload = ""; } /// True if action was successfull, otherwise false public bool Successful { get; set; } /// <summary> /// List of error or warning messages /// </summary> public List<string> Messages { get; set; } /// <summary> /// Payload of request to registry, containing properties formatted as CTDL - JSON-LD /// </summary> public string Payload { get; set; } }

Response class returned from delete endpoints.

public class RegistryAssistantDeleteResponse { public RegistryAssistantDeleteResponse() { Messages = new List<string>(); } /// <summary> /// True if delete was successfull, otherwise false /// </summary> public bool Successful { get; set; } /// <summary> /// List of error or warning messages /// </summary> public List<string> Messages { get; set; } }

Format Endpoints

The primary purpose of the formatting endpoints are to be able to 'test' making publishing calls. These endpoints are called with the same data that would be provided when publishing. The format endpoints do the same data validation as happens when calling the publish endpoints, and then formats the data as JSON-LD - as would be found in the registry. However, instead of publishing the data, it is returned to the caller.

Note that the Publish endpoint will format the data first, so you do not need to call both.

You can access these services by making HTTP POST requests to:

Format Data (only)

https://sandbox.credentialengine.org/assistant/{CTDL object type}/format

Example: Format Credential

https://sandbox.credentialengine.org/assistant/credential/format

Publish Endpoints

The publishing endpoints are used when you are ready to actually publish data to the registry.

You can access these services by making HTTP POST requests to:

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/{CTDL object type}/publish

Example: Publish Organization

https://sandbox.credentialengine.org/assistant/organization/publish

Delete Endpoints

The delete endpoints are used when you want to remove a document from the registry.

You can access these services by making HTTP DELETE requests to:

Delete a Document

https://sandbox.credentialengine.org/assistant/{CTDL object type}/delete

Example: Delete Credential

https://sandbox.credentialengine.org/assistant/credential/delete

The requirements for a delete request are as follows. Note: The API key is passed in the header of the request (see the Getting Your API Key section for details)

  • Your API Key
  • The CTID of the document to be deleted
  • The CTID of the organization making the request

Example HTTP DELETE request body:

Publishing Process

This section describes the process for publishing to the Registry via the Registry Assistant API.

Workflows

There are different types of workflows related to publishing:

  • First Party
  • Third Party
  • Trusted Third Party with Authority

First Party Workflow

First Party workflow is defined as: The owner of the data to be published also performs the publishing.

  1. The organization registers with the CE accounts site.
  2. A CTID is created for the organization. This CTID will used when publishing the organization, the PublishForOrganizationIdentifier property for all publishing requests, and the OwnedBy property when publishing credentials, etc.
  3. Upon approval, the organization will be given access to an API key (see Getting your API Key), that is used along with the CTID for their organization when calling the API to publish their data.
  4. The API process will validate whether a particular API key can be used to publish data for a particular organization CTID.

Third Party Workflow

Third Party workflow is defined as: The data organization has decided to have a third party publish data on their behalf.

  1. The organization, such as a state body, registers with the CE accounts site. Under their organization information, they would indicate that they plan to act as a third party publisher.
  2. The latter organization identifies 'client' organizations, and these bodies also register on the CE accounts site.
  3. As above, a CTID is created for the organization. This CTID will used when the third party publishes data for the organization
  4. After approval, a 'client' organization can submit a request to designate the third party organization to publish on their behalf.
  5. The third party organization must approve the request. Then CE staff will approve the completion of a third party publishing permission.
  6. Upon approval, the third party organization will be given access to an API key (see Getting your API Key).
  7. When publishing the third party organization would use their API key and the CTID for one of the client organizations.
  8. The Assistant API process will validate whether a particular API key can be used to publish data for a particular organization CTID.
  9. NEW - batch registration
    • A third party organizaion can register multiple organizations at one time, using either a bulk upload from the accounts site, or using an Accounts API (separate from the Assistant API).
      • Bulk Upload: A third party or trusted partner will see a Third Party Publishing tab on their account dashboard. Click the Upload/Register Organization link for Bulk Upload instructions (see image below).
      • Alternately, a Web API can be used to register organizations. See the Trusted Partner Publishing page for details.
Using the Accounts Bulk Upload

Trusted Third Party with Authority Workflow

Trusted Third Party with Authority workflow is defined as: The trusted third party has authorization to publish for the data organization, without the data organizations having to first create an account and give explicit authorization to the third party.

  1. The trusted organization, such as a state body, registers with the CE accounts site. Under their organization information, they would indicate that they plan to act as a third party publisher.
  2. This organization will likely have already had meetings with the CE team to discuss their plans. A CE team member has to designate an organization as a trusted partner.
  3. The trusted partner is responsible for validation of the organizations for whom they will be publishing.
  4. Typically the trusted partner will use either the accounts API endpoint or a bulk upload in the accounts site to register the organizations for whom they will be publishing.
  5. Both the API endpoint or bulk upload process will:
    • Validate the data
    • At least one contact is required. This person will be added as an administrator for the new organization.
    • The administrator will receive an email requesting confirmation of their account. This administrator can add additional contacts as needed.
    • The organization will be created, approved, and assigned an API key for publishing.
    • A third party relationship will be created and approved for publishing.
    • The provided contact will receive an email as notification that their organization has been added by the trusted partner.
  6. When publishing the third party organization would use their API key and the CTID for one of the client organizations as the PublishForOrganizationIdentifier parameter when publishing to the registry.
  7. The Assistant API process will validate whether a particular API key can be used to publish data for a particular organization CTID.

Sequence of Publishing

The Organization is always the first class to be published. It must exist in the registry before any credential, or learning opportunity, etc. can be published. The API has validation checks:

  • Checks if the organization has been registered and approved in the CE accounts site. If not the request will be rejected.
  • If a CTID is provided for the properties like owned by, offered by, accredited by, etc. the Assistant API will check if the record exists in the credential registry
  • If not found, an error will be returned

The Credential is typically the next document to publish. A credential can refer to a required learning opportunity or assessment using a condition profile. Where a credential can be published without referencing an assessment or learning opportuntity, neither of of the latter can be published if they are not referenced by a credential. Example of a credential that references a required learning opportunity using a 'requires' condition profile:

The API will check if the learning opportunity for the provided CTID (ctidForLearningOpportunity in the example above) is in the registry. If not, the publish request will still continue and a Warning will be returned as a reminder that the related learning opportunity should be published.

Serializing to JSON

While creating a JSON document is fairly straightforward, there should not be a need to manually code the JSON format. Libraries are available in most high level languages to serialize a class into JSON. For example The Newtonsoft library can be added to a C# project, and with one line a C# class can be serialized to JSON:

Sample showing one-line serialization of a C# class to JSON using the Newtonsoft library

string postBody = Newtonsoft.Json.JsonConvert.SerializeObject( myCSharpDataClass );

Pattern for Calling the Publishing API

All publish requests follow the same pattern. A publish request consists of three main parts:

  • The API key for your organization, passed in the header (see below)
  • The CTID of the organization that owns the data (If you are publishing on behalf of another organization, use that organization's CTID. Otherwise, use your organization's CTID)
  • The data itself

Passing Your API Key

The API key will be provided in the header of the request using the Authorization header and a label of ApiToken.

Adding an API key to an HTTP Request using HttpClient (C#)

The CTID for the data owner is provided in the body of the request along with the main data class.

Creating a request body for an organization (C#)

Assistant Key Input Classes

API Input Classes

When calling endpoints in the API, you only have to include the properties that are needed, or that you have available. Some of the samples in this section may reference related profiles such as condition profiles. If your process will not provide condition profiles, you don't need to include these properties in the classes that you use to fill out data to send to the API. Following are references where you may view or download sample input classes (in C# at this time).

The API input classes clarify the multiplicity of the input properties, which is not immediately clear by just reviewing the CTDL terms. As well special classes are used to organize some of the CTDL properties. For example:

  • Use of single multiplicity for Jurisdiction.MainJurisdiction
  • FrameworkItem for known Occupations, Industries, and Instructional Programs frameworks

Language Maps

October 31, 2018. Several major updates were made to how data is stored in the registry. These changes, for the most part, were transparent to API users. One of the additions was to store simple strings as language maps. For example, previously the ceterms:name property was formated as:

Previous name format

"ceterms:name": "Certificate in Electrical Specialist"

Properties defined as a language map are now an object with a property for each language provided. The property name is the BCP 47 language code (optionally including the region, e.g. "en" or "en-us"). This allows describing data for the same property in multiple languages, which in turn allows a system consuming the data to select the language(s) it wants to display.

Sample language map with one language

"ceterms:name": { "en": "Certificate in Electrical Specialist" }

Sample language map with multiple languages

"ceterms:name": { "en": "Certificate in Electrical Specialist", "es": "Certificado en Especialista Eléctrico", "ru": "Сертификат в области электротехники" }

As noted, one of the main tenets of the API is to simiplify publishing to the Credential Registry. To this end, users of the API can choose to provide data as a simple string or as a language map. If all of your data is in one language, the language provided in the inLanguage property will be used when formatting a language map for publishing to the registry.

In the API input classes, the language Map is defined as Dictionary with string keys and values (expressed in C# as Dictionary<string, string>).

See github for full LanguageMap class

Sample language map usage (C#)

Organization and Entity References

The Reference classes, EntityReference and OrganizationReference, were created to enable three scenarios:

  • The Uri to an Organization (or credential, etc.) in the registry
  • Just the CTID of the organization.
    The API will insert the correct domain name and path, based on the target server, to enable independence from the publishing environment.
  • A reference to an organization that has not been published to the registry

Entity Reference

When referencing a property that refers to a credential, assessment or learning opportunity, the assistant API uses an EntityReference. See the Entity Reference class in Github for all available properties.

This class, and the organization reference class enable a flexible approach to providing references to other entities, depending on what is available in the publishing system. There are three approaches:

  1. Provide just Id:
    • If the entity being referenced is already published in the registry, the full URI can be provided, like: https://sandbox.credentialengineregistry.org/resources/ce-a4041983-b1ae-4ad4-a43d-284a5b4b2d73.
    • Note: The convention is to provide the /resources URI, not the /graph URI.
  2. Provide just CTID:
    • Again, if the related entity is in the registry, or soon will be, then just the CTID can be provided.
    • The preference between providing a CTID or Id would be the CTID. Then the API can format the URL correctly based on the target credential registry and community where applicable.
    • There may be a case where a reference is needed for an entity that is in a different community that the current target (rare, and not yet completely handled). In this case, then the full URL should be provided in the Id property.
  3. Provide Reference Properties:
    • A reference can be made to an entity that doesn’t exist in the registry but does have a URL. In this case, the following can be provided:
      • Type (required). This would be one of ceterms:AssessmentProfile, ceterms:LearningOpportunityProfile, or one of the Credential subclasses such as ceterms:Badge, ceterms:Certification, etc.
      • Name (required)
      • SubjectWebpage (required)
      • Description (optional)
      • May 18, 2020. Several additional properties were added to the Entity Reference class
      • See the Entity Reference class in Github for all available properties.

Note: only one of the three options should be provided. The CTID is checked first, then the Id, then the external reference.

Sample usage (C#). See the Entity Reference class in Github for all available properties.

Partial EntityReference class. See the Entity Reference class in Github for all available properties.

Organization Reference

An OrganizationReference has a small number of required properties, plus the additional optional property of SocialMedia. The Organization reference is used in properties like ownedBy, offeredBy, accreditedBy, etc.

Like the EntityReference class, and the organization reference class enable a flexible approach to providing references to other entities, depending on what is available in the publishing system. This class will be commonly used for referencing QA organizations where the partner may not (and should not) know if the organization exists in the registry.
There are three approaches:

  1. Id:
    • If the entity being referenced is already published in the registry, the full URI can be provided, like: https://sandbox.credentialengineregistry.org/resources/ce-a4041983-b1ae-4ad4-a43d-284a5b4b2d73.
    • Note: The convention is to provide the /resources URI, not the /graph URI.
  2. CTID:
    • Again, if the related entity is in the registry, or soon will be, then just the CTID can be provided.
    • The preference between providing a CTID or Id would be the CTID. Then the API can format the URL correctly based on the target credential registry and community where applicable.
    • There may be a case where a reference is needed for an entity that is in a different community that the current target (rare, and not yet completely handled). In this case, then the full URL should be provided in the Id property.
  3. External Reference:
    • A reference can be made to an entity that doesn’t exist in the registry but does have a URL.
    • This class inherits from the EntityReference and adds one property: SocialMedia (a list of URLs to sites like LinkedId, Facebook, Twitter, etc.).
    • In this case, the following can be provided:
      • Name (required)
      • Organization type (class): (required): CredentialOrganization or QACredentialOrganization
      • SubjectWebpage (required)
      • Description (optional)
      • SocialMedia (optional)

Note: only one of the three options should be provided. The CTID is checked first, then the Id, then the external reference.

Sample Properties (C#). See full class in github.

Sample Usage (C#)

Occupations, Industries and Instructional Programs

Occupations, Industries and Instructional Programs that are related to credentials, learning opportunities, and others may be published to the credential registry. There are three ways to provide the latter data to the API, as shown below.

  • Using a structure class
  • Using a list of codes from a known framework
  • Using a list of text where the topic is not part of a framework

Items From a Formal Framework

The full details of a framework item can be published as credential alignment objects (see: CredentialAlignmentObject). The commonly used properties are:

  • framework - URL for the framework
  • frameworkName - the name of the framework
  • codedNotation - for example a SOC code of 49-9081.00 (Wind Turbine Service Technicians)
  • targetNode - public URL to this code
  • targetNodeName - name of this code
  • targetNodeDescription - a description of this code

The equivalent class in the API is FrameworkItem:

/// &lt;summary&gt; /// Coded Framework /// Examples /// SOC/O*Net - occupations /// NAICS - industries /// CIP - Classification of Instructional Programs /// &lt;/summary&gt; public class FrameworkItem { /// &lt;summary&gt; /// URL for framework /// &lt;/summary&gt; public string Framework { get; set; } /// &lt;summary&gt; /// Formal name of the framework /// &lt;/summary&gt; public string FrameworkName { get; set; } public LanguageMap FrameworkName_Map { get; set; } = new LanguageMap(); /// &lt;summary&gt; /// Experimental /// Allow a list of codes for a known framework and API will validate and format as a CredentialAlignmentObject /// Current supported frameworks: NAICS and O*Net /// How to designate the framework /// &lt;/summary&gt; public List&lt;string&gt; FrameworkCodeNotationList { get; set; } = new List&lt;string&gt;(); public string CodedNotation { get; set; } /// &lt;summary&gt; /// Name of the framework item, such as occupation or industry. /// targetNodeName /// &lt;/summary&gt; public string Name { get; set; } public LanguageMap Name_Map { get; set; } = new LanguageMap(); /// &lt;summary&gt; /// Description of the framework item /// targetNodeDescription /// &lt;/summary&gt; public string Description { get; set; } public LanguageMap Description_Map { get; set; } = new LanguageMap(); /// &lt;summary&gt; /// URI for the FrameworkItem /// &lt;/summary&gt; public string TargetNode { get; set; } /// &lt;summary&gt; /// Weight /// An asserted measurement of the weight, degree, percent, or strength of a recommendation, requirement, or comparison. /// &lt;/summary&gt; public decimal Weight { get; set; } }

Helper for O*Net/NAICS and CIP Codes

The API has short cut properties for handling occupations from the O*Net framework, industries from NAICS, and instructional programs from Classification of Instructional Programs (CIP). These properties only require the entry of a list of items using the coded notation only. The API will validate the codes, format the framework and target node data, and publish the data as a CredentialAlignmentObject. The helper properites are:

  • ONET_Codes
  • Naics
  • CIP_Codes

Alternative Framework Items

Feb. 22, 2019.

The API has helper properties for handling occupations, industries and instructional programs that are not part of a formal framework. The new properites are:

  • AlternativeIndustryType
  • AlternativeOccupationType
  • AlternativeInstructionalProgramType

Framework Examples

Following are examples of the different properties that can be used to publish framework data.

Example for adding Occupations using a FrameworkItem, a SOC list or alternate occupations to a credential request

public class OccupationsHelper { /// &lt;summary&gt; /// Example for populating Occupations for a Credential Request. /// The same approach would be used for other classes that support Occupations such as Assessments and LearningOpportunities. /// Possible Input Types /// - List of frameworks /// - list of occupation names /// - List of SOC codes /// /// &lt;/summary&gt; /// &lt;param name="request"&gt;&lt;/param&gt; public static void PopulateOccupations( Credential request ) { request.OccupationType = new List&lt;FrameworkItem&gt;(); //Using existing frameworks such as O*Net //occupations from a framework like ONet - where the information is stored locally and can be included in publishing request.OccupationType.Add( new FrameworkItem() { Framework = "https://www.onetonline.org/", FrameworkName = "Standard Occupational Classification", Name = "Information Security Analysts", TargetNode = "https://www.onetonline.org/link/summary/15-1122.00", CodedNotation = "15-1122.00", Description = "Plan, implement, upgrade, or monitor security measures for the protection of computer networks and information. May ensure appropriate security controls are in place that will safeguard digital files and vital electronic infrastructure. May respond to computer security breaches and viruses." } ); request.OccupationType.Add( new FrameworkItem() { Framework = "https://www.onetonline.org/", FrameworkName = "Standard Occupational Classification", Name = "Computer Network Support Specialists", TargetNode = "https://www.onetonline.org/link/summary/15-1152.00", CodedNotation = "15-1152.00", Description = "Plan, implement, upgrade, or monitor security measures for the protection of computer networks and information. May ensure appropriate security controls are in place that will safeguard digital files and vital electronic infrastructure. May respond to computer security breaches and viruses." } ); //Occupations not in a known framework //Occupations that are not in a framework can still be published using a list of strings. request.AlternativeOccupationType = new List&lt;string&gt;() { "Cybersecurity", "Forensic Scientist", "Forensic Anthropologist" }; //O*Net helper - ALternately provided a list of O*Net codes. //The Assistant API will validate the codes and format the output including the framework name and URL, the occupation, description, and code request.ONET_Codes = new List&lt;string&gt;() { "13-2099.01", "13-2052.00", "13-2061.00", "13-2051.00" }; } }

Example for adding Industries using a FrameworkItem, NAICS list or alternate industries to a credential request

public class Industries { /// &lt;summary&gt; /// Example for populating Industries for a Credential Request. /// The same approach would be used for other classes that support Industries such as Assessments and LearningOpportunities. /// Possible Input Types /// - List of frameworks /// - list of industry names /// - List of NAICS codes /// &lt;/summary&gt; /// &lt;param name="request"&gt;&lt;/param&gt; public static void PopulateIndustries( Credential request ) { request.IndustryType = new List&lt;FrameworkItem&gt; { //Using existing frameworks such as NAICS //occupations from a framework like NAICS - where the information is stored locally and can be included in publishing new FrameworkItem() { Framework = "https://www.naics.com/", FrameworkName = "NAICS - North American Industry Classification System", Name = "National Security", TargetNode = "https://www.naics.com/naics-code-description/?code=928110", CodedNotation = "928110", Description = "This industry comprises government establishments of the Armed Forces, including the National Guard, primarily engaged in national security and related activities." }, new FrameworkItem() { Framework = "https://www.naics.com/", FrameworkName = "NAICS - North American Industry Classification System", Name = "Regulation and Administration of Transportation Programs", TargetNode = "https://www.naics.com/naics-code-description/?code=926120", CodedNotation = "926120", Description = "This industry comprises government establishments primarily engaged in the administration, regulation, licensing, planning, inspection, and investigation of transportation services and facilities. Included in this industry are government establishments responsible for motor vehicle and operator licensing, the Coast Guard (except the Coast Guard Academy), and parking authorities." } }; //Industries not in a known framework //Industries that are not in a framework can still be published using a list of strings. request.AlternativeIndustryType = new List&lt;string&gt;() { "Cybersecurity", "Forensic Science", "Forensic Anthropology" }; //NAICS helper - ALternately provided a list of NAICS codes. //The Assistant API will validate the codes and format the output including the framework name and URL, the name, description, and code request.Naics = new List&lt;string&gt;() { "9271", "927110", "9281", "928110" }; } }

Example for adding Instructional Programs using a FrameworkItem, a SOC list or alternate instructional programs to a credential request

public class InstructionalPrograms { /// &lt;summary&gt; /// Example for populating Instructional Programs (example CIP) for a Credential Request. /// The same approach would be used for other classes that support Instructional Programs such as Assessments and LearningOpportunities. /// Possible Input Types /// - List of frameworks /// - list of program names /// - List of CIP codes /// &lt;/summary&gt; /// &lt;param name="request"&gt;&lt;/param&gt; public static void PopulatePrograms( Credential request ) { request.InstructionalProgramType = new List&lt;FrameworkItem&gt; { //Using existing frameworks such as CIP //programs from a framework like Classification of Instructional Program - where the information is stored locally and can be included in publishing new FrameworkItem() { Framework = "https://nces.ed.gov/ipeds/cipcode/search.aspx?y=56", FrameworkName = "Classification of Instructional Program", Name = "Medieval and Renaissance Studies", TargetNode = "https://nces.ed.gov/ipeds/cipcode/cipdetail.aspx?y=56&cip=30.1301", CodedNotation = "30.1301", Description = "A program that focuses on the study of the Medieval and/or Renaissance periods in European and circum-Mediterranean history from the perspective of various disciplines in the humanities and social sciences, including history and archeology, as well as studies of period art and music." }, new FrameworkItem() { Framework = "https://nces.ed.gov/ipeds/cipcode/search.aspx?y=56", FrameworkName = "Classification of Instructional Program", Name = "Classical, Ancient Mediterranean and Near Eastern Studies and Archaeology", TargetNode = "https://nces.ed.gov/ipeds/cipcode/cipdetail.aspx?y=56&cip=30.2202", CodedNotation = "30.2202", Description = "A program that focuses on the cultures, environment, and history of the ancient Near East, Europe, and the Mediterranean basin from the perspective of the humanities and social sciences, including archaeology." } }; //Instructional Programs not in a known framework //Instructional Programs that are not in a framework can still be published using a list of strings. request.AlternativeInstructionalProgramType = new List&lt;string&gt;() { "Cybersecurity 101", "Forensic Science 120", "Forensic Anthropology 400" }; //CIP code helper - ALternately provided a list of CIP codes. //The Assistant API will validate the codes and format the output including the framework name and URL, the name, description, and code request.CIP_Codes = new List&lt;string&gt;() { "31.0504", "31.0505", "31.0599", "31.9999" }; } }

Duration Items

DurationItem - used with DurationProfile class for the property EstimatedDuration. Rather than providing data in the ISO 8601 duration format (ex. for 10 hours, the format would be PT10H

The DurationItem has properties for Years, Months, Weeks, Days, Hours, and Minutes.

Duration Profile:

/// &lt;summary&gt; /// Duration Profile /// Either enter an ExactDuration or a range using Minimum duration, and maximum duration /// &lt;/summary&gt; public class DurationProfile { public DurationProfile() { MinimumDuration = new DurationItem(); MaximumDuration = new DurationItem(); ExactDuration = new DurationItem(); } /// &lt;summary&gt; /// Description of this duration profile - optional /// &lt;/summary&gt; public string Description { get; set; } public LanguageMap Description_Map { get; set; } = new LanguageMap(); public DurationItem MinimumDuration { get; set; } public DurationItem MaximumDuration { get; set; } public DurationItem ExactDuration { get; set; } }

Duration Item:

/// &lt;summary&gt; /// Enter either the Duration_ISO8601 value, OR the necessary combination of years, months, weeks, etc /// &lt;/summary&gt; public class DurationItem { /// &lt;summary&gt; /// A duration in the registry is stored using the ISO8601 durations format. /// P is the duration designator (for period) placed at the start of the duration representation. P is always required, even if only time related designators are included. /// Y is the year designator that follows the value for the number of years. /// M is the month designator that follows the value for the number of months. /// W is the week designator that follows the value for the number of weeks. /// D is the day designator that follows the value for the number of days /// T is the time designator that precedes the time components of the representation. /// H is the hour designator that follows the value for the number of hours. /// M is the minute designator that follows the value for the number of minutes. /// S is the second designator that follows the value for the number of seconds. /// Examples: /// P2Y - two years /// P10M - 10 months /// PT10H - 10 hours /// &lt;seealso cref="https://en.wikipedia.org/wiki/ISO_8601#Durations"/&gt; /// &lt;/summary&gt; public string Duration_ISO8601 { get; set; } public int Years { get; set; } public int Months { get; set; } public int Weeks { get; set; } public int Days { get; set; } public int Hours { get; set; } public int Minutes { get; set; } }

Sample Usage:

Getting Started

To call the publish API, you will need to make an HTTP POST request to the API endpoint specific to the data type being published. For example, to publish a credential you would use:

https://apps.credentialengine.org/assistant/credential/publish

NOTE: The remaining examples on this page will use URLs for the sandbox version of the credential registry.

With your request, include two things: First, you will need to pass your organization's API key (see Getting your API Key) as a request header using the format:

Authorization: ApiToken [YOUR API KEY]

Second, a JSON object with properties to publish. The provided JSON object will be specific to the type of data being published. The following sections will have examples of the properties for each data that may be published.

Top level classes in the Registry often need to reference one another. For example, a Credential might need to reference both the Organization that owns it, and an Assessment that it requires. The easiest way to provide valid references to these things is to ensure that things which need to be referenced are published before things that are doing the referencing. Usually this means that you should publish the Organization first, any required entities like assessments or learning opportunities second, and the credential(s) that reference these entities last. These references are all handled via the URIs explained in the CTID section of the Registry guide page.

The Registry Assistant API uses simiplified and flexible input classes. While all properties of CTDL are available, the input properties represent a Registry specific profile.

Examples of special or simplified classes and properities, follow below.

The Registry Assistant accepts data formatted using ordinary JSON. A special variant of JSON, JSON-LD, is used within the Registry. One of the features of the Registry Assistant API is that it handles conversion of ordinary JSON to JSON-LD for you. Explanations of JSON and JSON-LD are beyond the scope of this guide, but the remainder of this guide assumes at least a basic working knowledge of standard JSON. Note that the API does not care about the presence or lack of additional whitespace (sometimes known as "pretty printing") within your JSON, but for the purposes of readability, this guide will include it.

In some cases, a property can have multiple values. In these cases, you must always use an array if any values are present, even if there is only one value.

Upon successfully publishing data to the Registry, you will receive the resultant CER Envelope. The CER Envelope contains the entity that was published (the "payload") along with various other data about the publish event, such as the date and time the publish happened, the account responsible for it, cryptographic signature data to enable validation of the payload against tampering, and the identifier for the envelope itself (this is not the same as the CTID). While it is not necessary to reference a particular envelope in order to use the Registry, it may be useful to maintain a record of the envelope's ID within your system should you need to access a specific envelope in the future.

The general approach for each of the top level classes in the sections below works like this:

  1. Introduction to a top level class in CTDL and its Registry Assistant equivalent
  2. Required properties for that class
  3. Publishing a basic record using just the required properties and conversion of raw data to Registry Assistant API class to actual CTDL
  4. Recommended and optional properties for that class
  5. Summary

The high level steps for using the API include:

  • Determine the source of the target data from your environment
  • Develop process to retrieve the data
  • Get/View the latest input classes from Github: View/Download the C# API Input Classes here
  • These reference classes are in a C# syntax but can be easily adapted for alternate evironments
  • Map your to the latter input classes
  • Call the API

Publishing Your Organization

Introduction

Usually, the first class you will want to publish is the Organization class. This is the class that represents your organization, and you will use its CTID to reference the data within it. There are two types of organization classes, the most common is the CredentialOrganization class. If your organization focuses on providing quality assurance, you will want to publish the ceterms:QACredentialOrganization class instead.

NOTE: The Assistant API uses a simplied approach for publishing organizations. There is a single organization endpoint with a single Organization class. A Type property (like you will see used with Credentials) is used to designate the type of organization to publish. The type of organization is one of:

  • CredentialOrganization
  • QACredentialOrganization

References

To format or publish an Organization, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/organization/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/organization/publish

Required Properties

The Registry Assistant API uses a simplified version of the equivalent CTDL class to convey the data for an organization. This class is the same regardless of whether the resulting CTDL class is a QA Organization or not. Refer to the Minimum Data Policy for the required properties for the Credential Organization and QA Credential Organization classes.

Publishing a Basic Record

Your system will need to output the data in JSON format.

Recommended Properties

In order to maximize the utility of the Organization data in the Registry, we recommend you also include data for the recommended properties for the organization classes. See the recommended properties for the Credential Organization and QA Credential Organization classes. For example:

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The organization data itself will go in an Organization property:

Sample organization wrapper:

Below is some example code to publish a simple organization object, see github for the complete Organization Request class.

Sample organization publishing code (C#)

Summary

As you can see, once you get past the most basic properties, the Registry Assistant API alleviates a great deal of the complexity of the CTDL structure. This reduces the likelyhood of errors and ensures your data will be compatible with systems that consume data from the Registry.

Publishing Your Credential

Introduction

Once your organization has been published, you will often want to publish your first credential. For each credential you want to publish, you must first consider which type of credential it is. These types are defined by the subclasses of "Credential" in CTDL. Select the type that is most appropriate for your credential - note that you must pick exactly one type.

We recommend reviewing the credential type definitions to ensure that you’ve selected the most appropriate credential types.

Note that some credentials may be one type and also include a badge to represent them. In these cases, the badge is considered a type of verification, and is handled elsewhere in CTDL. The badge credential types (ceterms:Badge, ceterms:OpenBadge, and ceterms:DigitalBadge) are reserved for credentials that are exclusively defined as badges.

NOTE: The Assistant API, like for organization, uses a simplied approach for publishing credentials. There is a single credential endpoint with a single Credential class. A Type property is used to designate the type of credential to publish. Again refer to the credential type definitions to ensure that you’ve selected the most appropriate credential type.

References

To format or publish a Credential, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/credential/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/credential/publish

Required Properties

Once you have selected a type for your credential, your system will need to output at least the required properties. Refer to the Minimum Data Policy for the required properties for the Credential classes.

Publishing a Basic Record

Your system will need to output the data in JSON format.

Recommended Properties

In order to maximize the utility of the Credential data in the Registry, we recommend you also include data for the following properties. See the recommended properties for the Credential.

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The credential data itself will go in an Credential property:

Sample credential wrapper:

Below is some example code to publish a simple credential object, see github for the complete Credential Request class.

Sample credential publishing code (C#)

Credential Connections

Connections between credentials can be published using properties such as:

  • isPreparationFor
  • preparationFrom
  • isAdvancedStandingFor
  • advancedStandingFrom
  • isRequiredFor
  • isRecommendedFor

Below is an example of a connection to a credential for which the current credential will prepare a student:

Summary

As you can see, the Registry Assistant API greatly reduces the amount of data your system needs to carefully construct by abstracting away many of the intricacies of JSON-LD. However, it is very useful to learn about and understand JSON-LD for the benefit of your own system and to aid in any further development or debugging or usage of the data you get back from the Registry Assistant API.

This section has introduced publishing credentials with the more common properties. There are a lot of other properties that may be published for a credential, including:

Publishing Your Assessment

Introduction

The Assessment Profile class represents a description of a specific assessment related in some way to a credential. An assessment can be written, performance, and/or artifact-based. Generally, you only need to describe assessments that are significant and/or standalone (assessments such as exams, tests, and quizzes included in a learning opportunity do not need to be described unless there is a good reason to do so). For more information, review the CTDL Guide.

NOTE: An Assessment cannot be published that is not referenced by a credential. Typically a credential will use a Requires condition profile to reference a TargetAssessment. If an assessment publishing request is submitted where the assessment is not connected from a credential, it will be rejected.

References

To format or publish an Assessment, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/assessment/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/assessment/publish

Required Properties

The Registry Assistant API uses a simplified version of the Assessment Profile class to convey the data for an assessment. Refer to the Minimum Data Policy for the required properties for the Assessment class.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Assessment Profile data in the Registry, we recommend you also include data for the following properties. See the recommended properties for the Assessment Profile

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The assessment data itself will go in an Assessment property:

Sample assessment wrapper:

Below is some example code to publish a simple assessment object, see github for the complete Assessment Request class.

Sample assessment publishing code (C#)

Summary

The Registry Assistant API makes it easier to publish data about assessments.

Publishing Your Learning Opportunity

Introduction

The Learning Opportunity Profile is used to describe learning opportunities. In CTDL, a learning opportunity is a blanket term used to describe any significant educational experience, whether it is a one-day training class, a full degree program, or anything in between. For more information, review the CTDL Guide.

NOTE: A Learning Opportunity cannot be published that is not referenced by a credential. Typically a credential will use a Requires condition profile to reference a TargetLearningOpportunity. If a Learning Opportunity publishing request is submitted where the assessment is not connected from a credential, it will be rejected.

References

To format or publish a Learning Opportunity, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/learningopportunity/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/learningopportunity/publish

Required Properties

The Registry Assistant API uses a simplified version of the Learning Opportunity Profile class to convey the data for a learning opportunity. Refer to the Minimum Data Policy for the required properties for the Learning Opportunity class.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Learning Opportunity Profile data in the Registry, we recommend you also include data for the following properties. See the recommended properties for the Learning Opportunity Profile.

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The learning opportunity data itself will go in an LearningOpportunity property:

Sample learning opportunity wrapper:

Below is some example code to publish a simple learning opportunity object, see github for the complete Learning Opportunity Request class.

Sample learning opportunity publishing code (C#)

Summary

The Registry Assistant API makes it easier to publish data about learning opportunities.

Publishing Your CostManifest

Introduction

The Cost Manifest Profile class represents a description of a specific Cost Manifest for an organization. Generally, you only need to describe Cost Manifests that are used for many credentials, assessments or learning opportunities. Use of cost manifests will remove or reduce the reference to costs in many entities. For more information, review the CTDL Guide.

References

To format or publish an Cost Manifest, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/CostManifest/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/CostManifest/publish

Required Properties

The Registry Assistant API uses a simplified version of the Cost Manifest Profile class to convey the data for an Cost Manifest. Refer to the Minimum Data Policy for the required properties for this class.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Cost Manifest Profile data in the Registry, we recommend you also include data for the following properties:

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The cost manifest data itself will go in an CostManifest property:

Sample cost manifest wrapper:

Below is some example code to publish a simple cost manifest object:

Sample cost manifest wrapper, see github for the complete Cost Manifest Request class.

Summary

The Registry Assistant API makes it easier to publish data about Cost Manifests.

Publishing Your Condition Manifest

Introduction

The Condition Manifest Profile class represents a description of a specific Condition Manifest for an organization. Generally, you only need to describe Condition Manifests that are used for many credentials, assessments or learning opportunities. Use of condition manifests will remove or reduce the reference to conditions in many entities. For more information, review the CTDL Guide.

References:

To format or publish an Condition Manifest, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/ConditionManifest/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/ConditionManifest/publish

Required Properties

The Registry Assistant API uses a simplified version of the Condition Manifest Profile class to convey the data for an Condition Manifest. Refer to the Minimum Data Policy for the required properties for this class.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Condition Manifest Profile data in the Registry, we recommend you also include data for the following properties. See the recommended properties for the Condition Manifest Profile.

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The condition manifest data itself will go in an ConditionManifest property:

Below is some example code to publish a simple condition manifest object, see github for the complete Condition Manifest Request class.

Sample condition manifest publishing code (C#)

Summary

The Registry Assistant API makes it easier to publish data about Condition Manifests.

Publishing Your Competency Frameworks

Introduction

The Competency Framework class represents a description of a specific Competency Framework for an organization. For more information, review the CTDL Guide.

References

To format or publish an Competency Framework, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/CompetencyFramework/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/CompetencyFramework/publish

Required Properties

The Registry Assistant API uses a simplified version of the Competency Framework class to convey the data for an Competency Framework. Refer to the Minimum Data Policy for the required properties for a competency framework and Minimum Data Policy for a competency.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Competency Framework data in the Registry, we recommend you also include data for the following properties. See the recommended properties for the Competency Framework.

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The competency framework data itself will go in an CompetencyFramework property:

Sample competency framework wrapper:

Below is some example code to publish a simple competency framework object, see github for the complete Competency FrameworkRequest class.

Sample competency framework publishing code (C#)

Summary

The Registry Assistant API makes it easier to publish data about Competency Frameworks.

Publishing Your Concept Schemes

Introduction

The Concept Scheme class represents a description of a specific Concept Scheme for an organization. For more information, review the CTDL Guide.

To format or publish an Concept Scheme, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/ConceptScheme/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/ConceptScheme/publish

Required Properties

The Registry Assistant API uses a simplified version of the Concept Scheme class to convey the data for an Concept Scheme. Refer to the Minimum Data Policy for the required properties for a Concept Scheme and Minimum Data Policy for concepts.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Concept Scheme data in the Registry, we recommend you also include data for the following properties:

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The concept scheme data itself will go in an ConceptScheme property:

Sample concept scheme wrapper:

Below is some example code to publish a simple concept scheme object:

Sample concept scheme publishing code (C#)

Summary

The Registry Assistant API makes it easier to publish data about Concept Schemes.

Publishing Your Pathway

Introduction

The Pathway class represents a description of a specific pathway. In the context of Credential Engine, a pathway consists of structured sets of objectives and qualifying conditions defining points (milestones) along a route to fulfillment of a job, occupation or career. Qualifying conditions include homogeneous or heterogeneous sets of prescribed, preferred or recommended evidentiary artifacts such as competencies attained (knowledge, skills, abilities), relevant awards, other forms of recognition such as credentials earned and relevant experience. For more information, review the CTDL Guide.

To format or publish an Pathway, use the following endpoints:

Format Data (only). Recommended to use the format endpoint to validate the data without publishing.

https://sandbox.credentialengine.org/assistant/pathway/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/pathway/publish

Delete Data

https://sandbox.credentialengine.org/assistant/pathway/delete

References

See:

Required Properties

The Registry Assistant API uses a simplified version of the Pathway class to convey the data for an pathway. Refer to the Minimum Data Policy for the required properties for the Pathway and Pathway Component classes.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Pathway data in the Registry, we recommend you also include data for the following properties:

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The pathway data itself will go in an Pathway property:

Sample pathway wrapper:

Below is some example code to publish a simple pathway object:

Sample pathway publishing code (C#)

Summary

The Registry Assistant API makes it easier to publish data about pathways.

Publishing Your Pathway Set

Introduction

The PathwaySet class represents a description of multiple related pathways. A pathway set must include at least two pathways. A publish request can include the actual pathway data (using the Pathway input class in Github) or a reference to a pathway that has already been published. For more information, review the CTDL Guide.

To format or delete a PathwaySet, use the following endpoints:

Format Data (only). Recommended to use the format endpoint to validate the data without publishing.

https://sandbox.credentialengine.org/assistant/pathwaySet/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/pathwaySet/publish

Delete Data

https://sandbox.credentialengine.org/assistant/pathwaySet/delete

References

See:

References

The Registry Assistant API uses a simplified version of the Pathway Set class to convey the data for a pathway set. Refer to the Minimum Data Policy for the required properties for the PathwaySet.

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The pathwaySet data itself will go in an PathwaySet property:

Sample PathwaySet wrapper:

References

Below is some example code to publish a simple PathwaySet object:

Sample PathwaySet publishing code (C#)

Summary

The Registry Assistant API makes it easier to publish data about pathway sets.

Publishing Your Transfer Value Profiles

Introduction

The Transfer Value Profile class represents a description of a specific Transfer Value Profile. In the context of Credential Engine, a transfer value is used in education, training and credentialing to determine qualification for advanced standing. CTDL defines advanced standing as, reduces the time or cost required to earn or complete the referenced credential, assessment, or learning opportunity.

Transfer value can be determined based on a number of factors such as: completion of learning opportunities or assessments, work experience (e.g., military), demonstration of knowledge, skills or abilities. For more information, review the CTDL Guide.

References

To format or publish a Transfer Value Profile, use the following endpoints:

Format Data (only)

https://sandbox.credentialengine.org/assistant/transfervalue/format

Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/transfervalue/publish

Bulk Publish Data (automatically formats first)

https://sandbox.credentialengine.org/assistant/transfervalue/bulkpublish

Required Properties

The Registry Assistant API uses a simplified version of the Transfer Value Profile class to publish the data for a Transfer Value Profile. Refer to the Minimum Data Policy for the required properties for the Transfer Value Profile class.

Publishing a Basic Record

Your system will need to output the data above in JSON format. For example:

Recommended Properties

In order to maximize the utility of the Transfer Value Profile data in the Registry, we recommend you also include data for the following properties:

Sample

To publish the data, you will need to wrap it in an object that also contains a PublishForOrganizationIdentifier property. Naturally, this is where you specify the CTID of the owning organization (from the accounts site). The transfervalueprofile data itself will go in an Transfer Value Profile property:

Sample TransferValueProfile wrapper:

Below is some example code to publish a simple TransferValueProfile object:

Summary

The Registry Assistant API makes it easier to publish data about TransferValueProfiles.

Embedded Classes

Within CTDL, there are a number of classes that are published as objects nested within the top level classes described above. The Registry Assistant API works the same basic way. Some of the classes below may be used within more than one of the top level classes. In addition, more than one instance of the classes below may be present in many cases.

Condition Profile

Condition Profile is the workhorse of CTDL. It is a large profile encompassing a variety of properties that define the complex data which forms the glue between Credentials and most other entities: assessments, learning opportunities, competencies, other credentials, etc. Below are some of the most relevant properties; refer to the CTDL documentation for the full listing.

References

See:

Usage

The intended interpretation and usage of the data in a Condition Profile depends entirely on which property it is associated with. For instance, A Condition Profile attached to the "requires" property defines requirements for earning a Credential, whereas a Condition Profile attached to "recommends" is merely informational or advisory in nature, and does not define requirements. Often, such information only applies in certain circumstances - Condition Profile is designed to allow designating and describing these circumstances as well. Other properties also use Condition Profile to define connections between other entities in CTDL, but here we will focus on Credentials.

Note that multiple Condition Profiles defined under the same property (e.g., requires) are considered to all apply to that property if the person pursuing the credential meets the conditions of those profiles. For example, if a credential has 3 Condition Profiles under "requires" and a person pursuing that Credential meets the conditions for two of those Condition Profiles, then that person must meet all of the conditions defined in both of those profiles to earn the Credential.

Cost Profile

Cost Profile is a detailed class meant to convey how much something costs in the context of certain circumstances. There are many situations in which the cost of something depends on some factor of the person trying to earn it, such as residency, military status, citizenship, etc. Use as many Cost Profiles as are necessary to convey the different overall costs for these different combinations of circumstances. You may provide one "general" Cost Profile, and only need to provide additional Cost Profiles for particular situations that are relevant to your credential. You should not provide a Cost Profile for every possible combination of the properties/vocabulary terms listed below unless each of those combinations is significantly different.

References

See:

Usage

A Credential Registry cost profile includes one direct cost and price per profile. The Assistant API helps simplify the entry of cost profiles with multiple costs. The main cost profile information is provided once, and the individual cost types and price can be provided in a list.

/// &lt;summary&gt; /// CostProfile class /// 2018-09-02 Where LanguageMap alternates are available, only enter one (string or language map). The system will check the string version first. /// &lt;/summary&gt; public class CostProfile { /// &lt;summary&gt; /// Inialize lists /// &lt;/summary&gt; public CostProfile() { Jurisdiction = new List&lt;Jurisdiction&gt;(); CostItems = new List&lt;CostProfileItem&gt;(); Condition = new List&lt;string&gt;(); } /// &lt;summary&gt; /// Cost Details - A URL /// Required /// &lt;/summary&gt; public string CostDetails { get; set; } /// &lt;summary&gt; /// Description of cost profile /// Required /// &lt;/summary&gt; public string Description { get; set; } /// &lt;summary&gt; /// Alternately can provide a language map /// &lt;/summary&gt; public LanguageMap Description_Map { get; set; } = new LanguageMap(); /// &lt;summary&gt; /// Name for this cost profile /// Optional /// &lt;/summary&gt; public string Name { get; set; } /// &lt;summary&gt; /// Alternately can provide a language map /// &lt;/summary&gt; public LanguageMap Name_Map { get; set; } = new LanguageMap(); /// &lt;summary&gt; /// A currency code, for ex USD /// Optional /// &lt;/summary&gt; public string Currency { get; set; } /// &lt;summary&gt; /// List of cost items /// Provide a list of individual costs including /// - DirectCostType - using concept scheme /// - Price /// - ResidencyType /// - AudienceType /// - PaymentPattern /// Optional /// &lt;/summary&gt; public List&lt;CostProfileItem&gt; CostItems { get; set; } /// &lt;summary&gt; /// Start date or effective date of this cost profile /// Optional /// &lt;/summary&gt; public string StartDate { get; set; } /// &lt;summary&gt; /// End date or expiry date of this cost profile /// Optional /// &lt;/summary&gt; public string EndDate { get; set; } /// &lt;summary&gt; /// List of condtions, containing: /// A single condition or aspect of experience that refines the conditions under which the resource being described is applicable. /// Optional /// &lt;/summary&gt; public List&lt;string&gt; Condition { get; set; } /// &lt;summary&gt; /// Alternately use a LanguageMapList for the conditions /// &lt;/summary&gt; public LanguageMapList Condition_Map { get; set; } = new LanguageMapList(); /// &lt;summary&gt; /// List of jurisdictions /// Optional /// &lt;/summary&gt; public List&lt;Jurisdiction&gt; Jurisdiction { get; set; } }

Populating a Cost Profile

The following shows how that latter code is formatted as JSON

Cost Profile As JSON

The following shows how that latter code is formatted as JSON

Financial Assistance Profile

Financial Assistance Profile is a class that describes financial assistance that is offered or available. Provide the data that is most appropriate for your situation.

References

See:

Usage

A Financial Assistance Profile must include a name and at least one of the following: Description, Subject Webpage, or Financial Assistance Type.

The financial assistance type is a list of one or more concepts that must exist in the ceterms:FinancialAssistance concept scheme. Multiple terms may be included:
FinancialAssistanceType = new List() { "Military", "Veteran" }

Use Financial Assistance Value to provide the actual value of financial assistance available. This property is a list of QuantitativeValues. The QuantitativeValue includes the UnitText property. Financial Assistance Value, the UnitText if present, is expected to be a currency. It is not required if a description is available.

Duration Profile

Duration Profile is a small utility class meant to convey how long something takes. In this case, it is used to indicate approximately how long it will take for the average person to earn this credential. This is often the same as the length of a degree credential's degree program, or the length of a certificate's assessment. Duration Profile allows expressing either an exact duration or a minimum and maximum duration. Provide the data that is most appropriate for your situation.

References

See:

Usage

A Duration Profile can contain an exact duration or minimum and maximum durations. A description can be used to describe the above. Alternately just the descripion can be provided to describe more intricate scenarios.

Data in the Registry

Data in the registry is wrapped in a common container, called an envelope. The data your system publishes is transformed into the decoded_payload property of the envelope, and is tracked with other properties. The Registry generates and maintains this structure; you do not publish an envelope.

Structure of a Registry Envelope

The properties for an enevelope are:

PropertyDefinition
envelope_communityThe community related to this envelope. Each community has a different schema for the resource to be encoded.
envelope_idThe unique identifier for this envelope, defined as a UUID
envelope_ceterms_ctidThe unique CTID for the primary document in this envelope.
envelope_ctdl_typeThe CTDL type of the primary document in this envelope, for example: ceterms:CredentialOrganization
envelope_typeCurrently will only have a type of resource_data.
envelope_versionThe version that our envelope is using. The current version is "1.0.0"
resourceA string containing the JWT encoded content. The original resource should follow the corresponding envelope_community's schema.
decoded_resourceThe Resource in the original decoded form.
resource_formatOnly json is allowed.
resource_encodingThe algorithm used to encode the resource. Currently we only support "jwt"
resource_public_keyThe public key, in PEM format, whose private part was used to sign the resource. This is strictly needed for signature validation purposes.
publisher_id
secondary_publisher_id
node_headers

Headers for the envelope

PropertyDefinition
revision_historyContains list of revision history events for the data.
created_atDate (UTC) the data was orginally published to the registry.
updated_atDate (UTC) the data was last published to the registry. NOTE: If a document published to the registry has the same contents as the current existing document, an update is not done, and the updated_at date is not changed.
deleted_atDate (UTC) the data was deleted (tombstoned/virtually deleted) from the registry.

Sample envelope structure

Retrieving Data from the Registry

A single record in the registry can be accessed using several methods:

Controlled Vocabularies

Within CTDL, a number of properties leverage controlled vocabularies (also called "concept schemes") to convey concepts in a format that can be understood across multiple systems. A controlled vocabulary works like a miniature schema, defining a set of terms and exactly what those terms mean. In many cases, more than one term from a controlled vocabulary can be used to more accurately define the data being described.

Refer to the Concept Schemes section of the terms page to review the concept schemes in CTDL.