$sp API
Service Portal provides a set of convenience methods found on the global $sp
object, which is available in any widget server script.
Method | Description |
---|---|
canReadRecord(Mixed, opt String): boolean | Official Documentation Returns true if the user can read the specified GlideRecord. |
getCatalogItem(String): Object | Official Documentation Returns a model and view model for a sc_cat_item or sc_cat_item_guide. |
getDisplayValue(String): String | Official Documentation Returns a display value from a field on a record in this order: 1. The widget's sp_instance* record 2. |
getField(GlideRecord, String): Object | Official Documentation Returns {display_value, label, type, value} for a given field on a GlideRecord. |
getFields(GlideRecord, String): Array | Official Documentation Like getField Checks the specified field names, and returns a comma seperated list of valid names. |
getFieldsObject(GlideRecord, String) | Official Documentation Checks the specified field names, and returns an object containing the valid names. |
getForm(String table, String sys_id, /Optional String/ encodedQuery, /Optional String/ view) | Official Documentation Returns the form |
getListColumns(String tableName, String view): | Official Documentation Returns a list of the specified table's columns in the specified view |
getMenuHREF(GlideRecord): String | Official Documentation Returns the (?id=) portion of the URL based on the sp_menu type. |
getMenuItems(String sys_id): Array | Official Documentation Returns the menu items for the specified instance |
getParameter(String): Object | Official Documentation Returns the value of a given key from the query string or post body. |
getPortalRecord(): GlideRecord | Official Documentation Returns the portal's GlideRecord. |
getRecord(): Glide | Official Documentation Returns the GlideRecord for the current sp_instance*. Returns null if the widget is embedded by another widget. |
getRecordDisplayValues (Object, GlideRecord, String): void | Official Documentation Copies display values for the specified field names from a GlideRecord into the data parameter. |
getRecordElements(Object, GlideRecord, String): void | Official Documentation Copies the value and display value for the specified field names from a GlideRecord into the data parameter. |
getRecordValues (Object, GlideRecord, String): void | Official Documentation Copies values for the specified field names from a GlideRecord into the data parameter. |
getStream(String, String): Object | Official Documentation Get the activity stream for a record. |
getUserInitials() | Official Documentation Returns the user's initials as a string. |
getValue(String): Object | Official Documentation Like getDisplayValue except that it returns the value instead of the display value. |
getValues(Object, String): void | Official Documentation Copies values from the request or instance into the data parameter. |
getValues(Object): void | Official Documentation Copies values from the widget's sp_instance GlideRecord into the data parameter. |
getWidget(String, Object): Object | Official Documentation Returns a widget model for embedding a widget inside another widget. |
getKBRecord(): Unknown | Not documented - Returns the portal's KB record where the workflow state is published. |
getKBCount(): Unknown | Not documented - Returns the number of Knowledge Base articles. |
getKBCategoryArticles(): Unknown | Not documented - Returns KB articles in the specified category and its subcategories. Pass 'limit' to limit the number of articles returned. |
getKBTopicArticles(): Unknown | Not documented |
getKBTopCategoryID(): Unknown | Not documented - Returns the top category in the hierarchy containing the specified category. |
getKBSiblingCategories(): Unknown | Not documented - Returns KB categories with same parent as the specified category. |
getSCRecord(): Object | Returns sc_cat_item record for the portal's catalog with sys_class_name != sc_cat_item_wizard and active = true in the query. GlideRecord returned has not yet triggered the query. |
showCatalogPrices(): Unknown | Not documented - Is an object |
saveVariables(): Unknown | Not documented |
buildThemeVariableModel(): Unknown | Not documented |
getVariablesArray(): Unknown | Not documented - Returns the tables variables as an object. |
getWidgetFromInstance(): Unknown | Not documented - Returns a widget from the specified widget instance. |
getRecordVariablesArray(): Unknown | Not documented - Returns the records variables. |
getFilterBreadcrumbs(): Unknown | Not documented - Returns an array of objects where each object contains the breadcrumb label, value, and flags for if fixed and if removed |
logStat(String type, String table, String id, opt String comments): void | Create a new entry in the sp_log table with a table name, a record sys_id from that name, and some type and optional comments. Handy for doing things like logging searches or visits to pages, etc. |
getInstanceRecord(): Unknown | Not documented - Returns the widget instances GlideRecord |
log(): Unknown | Not documented - Sends the specified message to the log console. |
saveRecord(): Unknown | Not documented - Saves or updates the current record. |
logSearch(): Unknown | Not documented - Adds a record to the Service Portal Statistics logs. |
$sp.getPortalRecord()
Useful for getting the current portal context. It returns the sp_portal GlideRecord if there is one.
- $sp.getPortalRecord( )
- Parameters
- None
- Returns
- (GlideRecord) The sp_portal record of the current portal context or null.
- Parameters
Server Script
(function() {
var portalGr = $sp.getPortalRecord();
data.logo = portalGr.getDisplayValue("logo");
data.homepage = portalGr.getDisplayValue("homepage.id");
})();
HTML Template
<div>
<img ng-src="{{::c.data.logo}}" />
<a href="?id={{::c.data.homepage}}">Click here to go home</a>
</div>
Result
$sp.getWidget()
Gets a widget by id or sys_id, executes that widget's server script using the provided options, then returns the widget model.
- $sp.getWidget( widget_id, options ): Object
- Parameters
- (String) widget_id
Can be a widget_id or widget sys_id. - (Object) options
An object to pass to the widget's server script. Refer to this object as options in your server script.
- (String) widget_id
- Returns
- (Object) A widget model to be used with \
.
- (Object) A widget model to be used with \
- Parameters
Server Script
data.myWidget = $sp.getWidget('widget_id', {p1: param1, p2: param2});
HTML Template
<sp-widget widget="c.data.myWidget"></sp-widget>
For more information and examples refer to the Embedded Widgets guide.
$sp.canReadRecord()
Useful for quickly determining if a record is valid and if the logged-in user has access to it.
If the record type is kb_knowledge, sc_cat_item, or sc_category it also checks if the user can view that item.
- $sp.canReadRecord( gr ): Boolean
- Parameters
- (GlideRecord) gr
A glide record
- (GlideRecord) gr
- Returns
- (Boolean) True if the record is valid and readable
- Parameters
- $sp.canReadRecord( table, sys_id ): Boolean
- Parameters
- (String) table
A table name to query. - (String) sys_id
The record sys_id to query.
- (String) table
- Returns
- (Boolean) True if the record is valid and readable
- Parameters
Server Script
data.items = [];
data.userName = gs.getUserDisplayName();
var gr = new GlideRecord("sc_cat_item");
gr.query();
while(gr.next() && data.items.length < 10) {
if ($sp.canReadRecord(gr)) {
data.items.push(gr.getDisplayValue("name"));
}
}
HTML Template
<div class="panel panel-default">
<div class="panel-heading">Hi, {{c.data.userName}}!</div>
<div class="panel-body">
Here are some things you can order:
<ul><li ng-repeat="item in c.data.items">{{item}}</li></ul>
</div>
</div>
Result
Notice how the list of items is different based on the logged in user
$sp.getCatalogItem()
A quick way to get all of the data necessary to render and order a catalog item using \
The following example demonstrates how to use getCatalogItem and \
- $sp.getCatalogItem( sys_id ): Object
- Parameters
- (String) sys_id
The sys_id of the catalog item(sc_cat_item) or order guide(sc_cat_item_guide).
- (String) sys_id
- Returns
- (Object) An object containing the catalog item variable model, view, sections, pricing and client scripts.
- Parameters
Server Script
(function() {
var sys_id = $sp.getParameter("sys_id")
data.catItem = $sp.getCatalogItem(sys_id);
})();
Client Script
function($http, spUtil) {
var c = this;
var submitting = false;
c.getIt = function() {
if (submitting) return;
$http.post(spUtil.getURL('sc_cat_item'), c.data.catItem).success(function(response) {
if (response.answer) {
c.req = response.answer;
c.req.page = c.req.table == 'sc_request' ? 'sc_request' : 'ticket';
}
});
}
}
SCSS
.img-bg {
padding: 5px;
background-color: $brand-primary;
}
.img-responsive {
margin: 0 auto;
}
.cat-icon {
display: block;
margin: -40px auto 0;
}
HTML Template
<div class="col-sm-4">
<div class="panel panel-default">
<div class="img-bg">
<img ng-src="{{::data.catItem.picture}}" class="img-responsive" />
</div>
<span class="cat-icon fa fa-stack fa-lg fa-3x hidden-xs">
<i class="fa fa-circle fa-stack-2x text-success"></i>
<i class="fa fa-desktop fa-stack-1x fa-inverse"></i>
</span>
<div class="panel-body">
<p class="lead text-center">{{::data.catItem.name}}</p>
<ul class="list-unstyled">
<li class="text-center" ng-if="::data.catItem.price">${Price}: {{::data.catItem.price}}</li>
</ul>
<sp-model form-model="::data.catItem" mandatory="mandatory"></sp-model>
<p ng-if="c.req" class="text-center text-success">
${Request created!} <a href="?id={{c.req.page}}&table={{c.req.table}}&sys_id={{c.req.sys_id}}">{{c.req.number}}</a>
</p>
<button ng-if="!c.req" class="btn btn-default btn-block" ng-click="c.getIt()">${Get it}</button>
</div>
</div>
</div>
Result
$sp.getDisplayValue()
Returns the display value of a given field (if it exists and has a value) from either the widget's sp_instance or the sp_portal record. Refer to the following diagram:
This map visualizes a service portal page with one widget on it. Calling $sp.getDisplayValue("title") would return the display value of the title field on the widget's sp_instance record. If the title field didn't exist or was empty, then it would try the same operation on the the sp_portal record for the current portal context.
Note - Embedded widgets do not have sp_instance records.
- $sp.getDisplayValue( fieldName ): String
- Parameters
- (String) fieldName The field name to get the display value of.
- Returns
- (String) A display value from either the sp_instance record or sp_portal record.
- Parameters
Server Script
(function() {
data.title = $sp.getDisplayValue("title");
data.catalog = $sp.getDisplayValue("sc_catalog");
})();
HTML Template
<div>
<h1>sp_instance.title: {{::data.title}}</h1>
<h1>sp_portal.sc_catalog: {{::data.catalog}}</h1>
</div>
Result
$sp.getRecordElements()
Copies display values for the specified field names from a GlideRecord into the data parameter.
-
$sp.getRecordElements( Object, GlideRecord, String ): void
-
Parameters
- (Object) data Must pass data object instantiated by the server.
- (GlideRecord) GlideRecord Any GlideRecord of data
- (String) String Comma-delimited string of fieldnames
- Returns
- (Void)
Field objects will be added to data
Server Script
- (Void)
Field objects will be added to data
-
(function($sp) {
var gr = new GlideRecord("tablename");
var fieldnames = "sys_id,field_name";
$sp.getRecordElements(data, gr, fieldnames);
})($sp);
$sp.getValue()
Returns the value of a given field (if it exists and has a value) from either the widget's sp_instance or the sp_portal record. See getDisplayValue for more info.
- $sp.getValue( fieldName ): Object
- Parameters
- (String) fieldName The field name to get the value of.
- Returns
- (Object) A value from either the sp_instance record or sp_portal record.
- Parameters
Server Script
(function() {
data.title = $sp.getValue("title");
data.catalog = $sp.getValue("sc_catalog");
})();
HTML Template
<div>
<h1>sp_instance.title: {{::data.title}}</h1>
<h1>sp_portal.sc_catalog: {{::data.catalog}}</h1>
</div>
Result