• Calling SND APIs
• Packages API
• Categories API
• Project API
• Events API
• SND JSON
• API Testing Framework for Simulating UI

Calling SND APIs

To call the snd API from another LabKey module, use LABKEY.Ajax.request. For example:

LABKEY.Ajax.request({
	url: LABKEY.ActionURL.buildURL("snd", "getEvent.api"),
    	method: 'POST',
    	success: onSuccess,
    	failure: onError
});

function onSuccess(results) {
	alert(“Success!”);
}

function onError(errorInfo) {
	alert(“Failure!”);
}

Calling LABKEY.Query APIs

See LABKEY.Query JS API documentation.

Packages

A package is the building block of the SND schema. A package is the detailed representation of a node in the hierarchy, containing metadata about the procedure, workflow step, or other type of data the node represents. The following APIs are defined for package searching, creation, editing, viewing and deletion.

SND APIs

• savePackage: (New) Saves a new package or update an existing package. Once a package is "In use", determined by the "Has Event" calculated column, then the domain and corresponding property descriptors will not be updatable. Used in the Package UI to save or save draft for new, edit, or clone.
• getPackages: (New) Finds one or more packages by their package IDs. Returns an array containing package JSON datas. See JSON for a package below. Used in the Package UI for viewing or initial data for editing or cloning packages.

• LABKEY.Query.selectRows: Get a list of package Id’s and abbreviated package info. Used for package list UI. Includes Has Event and Has Project columns for grouping and filtering in the UI.
• LABKEY.Query.deleteRows: First checks if package is in use. If so, do not allow to delete. If package is not in use, domain and property descriptors are also deleted.

savePackage

Input:

{
	pkgId: int - only if updating or cloning,
	description: string - (required),
	active: boolean - (required),
	repeatable: boolean - (required),
	clone: boolean - (optional)
	narrative: string - (required),
	testIdNumberStart: int - (optional) used for testing only,
	categories: [categoryId (int), ...] - (optional),
	attributes: [Property Descriptors] - (optional),
	extraFields: [Property Descriptors] - (optional)
	subPackages: [{ - (optional)
		superPkgId: int - (required),
		sortOrder: int - (required),
		repeatable: boolean - (required),
		required: boolean - (required)
	},
	...]
}

Output: No JSON

getPackages

Input:

{
	packages:[
		packageId: int,
	…] (required),
	excludeExtraFields: boolean (optional) - Default false. Used to speed up metadata queries for the UI.
	excludeLookups: boolean (optional) - Default false. Used to speed up metadata queries for the UI.
	includeFullSubpackages: boolean (optional) - Default false. Returns the full super package hierarchy.
}

Output: Package.

Categories

Updated or useful APIs to be called on snd.PkgCategories table

• LABKEY.Query.saveRows: Saves a list of all categories, preserving categoryId.
• LABKEY.Query.selectRows: Return a list of all categories. Used for category editing as well as for populating category drop down menus. Includes an "In Use" calculated column.
• LABKEY.Query.deleteRows: If any categories are deleted, the CategoryJunction table is updated. If categories are "In use" (meaning attached to a package) they cannot be deleted.

Projects

SND APIs

• saveProject: (New) Used for creating, editing, and revising Projects. Includes draft state, revision number, and project type.
• Create Project: isEdit and isRevision set to false. The revision is saved as zero. Must contain a start date, description and reference ID.
• Edit Project: isEdit is set to true and isRevision is set to false. Project ID and Revision are not editable and do not change on edit.
• Revise Project: isEdit is set to false and isRevision is set to true. Increments the revision number by one. It does not delete the project being revised. Any fields other than project ID can be updated as part of a revision.
• getProject: (New) Select all the project information for a given project ID. See JSON for a Project below. Used in the Project UI for viewing or inital data for editing or revising.

• LABKEY.Query.selectRows: Get a list of abbreviated project/revision data including the hasEvent field (The snd.Events table contains a reference to the project the event was created toward. The Has Event boolean for each project reflects whether such an event exists.).
• LABKEY.Query.deleteRows: Will not allow deleting an in use object (object with an event). Only allows deleting the most recent project. Will delete the approved list items in project items.

saveProject

Input:

{
	projectId: int - Only for project edits and revisions,
	revisionNum: int - Only for project edits and revisions,
	description: string (required),
	Active: boolean (required),
	referenceId: int (required),
	startDate: string (required) (yyyy/MM/dd),
	endDate: string (optional) (yyyy/MM/dd),
	endDateRevised: string (optional) - End date for previous revision if doing revision (yyyy/MM/dd)
	isEdit: boolean (optional) - default false,
	isRevision: boolean (optional) - default false,
	extraFields: [Property Descriptors] - (optional),
	projectItems: [ (optional)
		Active: boolean (required),
		superPkgId: int (required)
	]
}

Output: No JSON

getProject

Input:

{
	projectId: int - (required),
	revisionNum: int (required)
}

Output: Project

Events API

SND APIs

• getEvent: (New) Retrieves event and attribute data and generates the json for the event. Aggregates event data from snd.events, snd.eventnotes, snd.eventdata and attribute data from the exp module. Flags:
• getTextNarrative: boolean (Optional) Default is false. Includes the full event narrative in text form in the returned JSON. Includes newline and tab characters.
• getRedactedTextNarrative: boolean (Optional) Default is false. Includes full event narrative with redacted values inserted for attribute values where redacted values are defined. Redacted values are defined using the package creation UI.
• getHtmlNarrative: boolean (Optional) Default is false. Includes full event narrative in HTML format in the returned JSON. Includes div and span tags with specific classes to define the data defining the narrative and where CSS formatting should occur
• getHtmlNarrative: boolean (Optional) Default is false. Includes full event narrative in HTML format with redacted values inserted for attribute values where redacted values are defined.
• saveEvent: (New) Used for creating a new event or editing an existing event. Takes the json representation of an event, including attribute data, and populates snd.events and snd.eventnotes.
• validateOnly: boolean (Optional) Default is false. When true, all validation triggers are run, but no insert or update is performed. See: SND: Event Triggers

• LABKEY.Query.deleteRows: If an event is deleted from snd.Events, then its related information in snd.EventData, snd.AttributeData (virtual table), snd.EventNotes and snd.EventsCache will also be deleted.

getEvent

Input:

{
	eventId: int (required),
	getTextNarrative: boolean (optional) - default false,
	getRedactedNarrative: boolean (optional) - default false,
	getHtmlNarrative: boolean (optional) - default false,
	getRedactedHtmlNarrative: boolean (optional) - default false
}

Output: Event.

saveEvent

Input:

event: {
	eventId: int - (optional) only if updating an existing event,
	date: date string - (required) event date (yyyy-MM-ddThh:mm:ss ISO8601),
	projectIdRev: string - (required) “projectId|projectRev”,
	subjectId: string - (required) ,
	qcState: string - (required) ,
	note: string - (optional),
	extraFields: [Property Descriptors] - (optional) depends on customization,
	eventData: [{ - (optional) event with no data would not have these.
		eventDataId: int - (optional) for updating,
		superPkgId: int - (required),
		extraFields: [Property Descriptors] - (optional) depends on customization,
		attributes: [{
			propertyId: int  - (required) either propertyId or propertyName is required,
			propertyName: string  - (required),
			Value: string  - (required),
		},
		…]
	}
	…]
}

Output: Event.

SND JSON

Property Descriptor

This provides metadata about an attribute or field.

{
	conceptURI: string,
	defaultValue: string,
	format: string,
	label: string,
	lookupQuery: string,
	lookupSchema: string,
	name: string,
	propertyId: int,
	rangeURI: string,
	redactedText: string,
	required: boolean,
	scale: int,
	validators: [Property Validators]
	value: string
}

Property Validator

Validation for attributes.

{
	description: string,
	errorMessage: string,
	expression: string - ex. “~gte=1&~lte=300”,
	name: string,
	type: string
}

Exception

Event, EventData or AttributeData exceptions from the event APIs.

{
	severity: string - Error, Warning or Info,
	message: string
}

Event

Full Event JSON:

{
	eventId: int,
	date: date string - event date (yyyy-MM-ddThh:mm:ss ISO8601),
	projectIdRev: string - “projectId|projectRev”,
	subjectId: string,
	qcState: string,
	note: string,
	exception: Exception - Only if there are Event level exceptions to report,
	redactedHtmlNarrative: string - Only if requested,
	htmlNarrative: string - Only if requested,
	redactedTextNarrative: string - Only if requested,
	testNarrative: string - Only if requested,
	extraFields: [Property Descriptors] - ex. USDA Code,
	eventData: [{
		eventDataId: int,
		exception: Exception - Only if there are EventData level exceptions to report
		superPkgId: int,
		narrativeTemplate: string,
		extraFields: [Property Descriptors],
		attributes: [{
			propertyId: int,
			propertyName: string,
			Value: string,
			propertyDescriptor: Property Descriptor (not for input),
			exception: Exception - Only if there are AttributeData exceptions to report
		},
		…]
	}
	…]
}

Package

Returned from the getPackage API.

{
	pkgId: int,
	superPkgId: int,
	description: string,
	active: boolean,
	repeatable: boolean,
	narrative: string,
	hasEvent: boolean,
	hasProject: boolean,
	categories: [categoryId (int), ...],
	attributes: [Property Descriptors],
	extraFields: [Property Descriptors] - Not when excludeExtraFields is true
	subPackages: [{
		superPkgId: int,
		pkgId: int,
		description: string,
		narrative: string,
		sortOrder: int,
		repeatable: boolean,
		required: boolean,
		attributes[Property Descriptors] - Only when includeFullSubpackages is true
		subPackages:[...]
	...],
	attributeLookups: [lookup table (string)] - Not when excludeLookups is true
}

Project

Returned from the getProject API.

{
	projectId: int,
	description: string,
	revisionNum: int,
	active: boolean,
	startDate: string - date string (yyyy/MM/dd),
	endDate: string - only if set (yyyy/MM/dd),
	referenceId: int,
	hasEvent: boolean,
	extraFields: [Property Descriptors]
	projectItems: [{
		projectItemId: int,
		active: boolean,
		superPkgId: int
	...],
}

API Testing Framework for Simulating UI

Developers can test data entry user interface by testing the creation of events and attribute data using the API Testing framework. This JavaScript API for entering and retrieving data defined by a super package and associated with an event. You can test the business rules, all the JSON properties, and error cases for these APIs.

The tests iterate through a configurable list of tests in a separate file defined in a standard format. The desired results are stored in an external file for comparison.

Examples:

• Package_test_script.txt
• Project_test_script.txt

To run the tests, navigate to your SND project and go to "snd-test.view#" there. Click Run Tests.

Related Topics

• Structured Narrative Datasets
• Define Redacted Values
• SND: Event Triggers