$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.

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.
  • Returns
    • (Object) A widget model to be used with \.

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
  • Returns
    • (Boolean) True if the record is valid and readable
• $sp.canReadRecord( table, sys_id ): Boolean
  • Parameters
    • (String) table
      A table name to query.
    • (String) sys_id
      The record sys_id to query.
  • Returns
    • (Boolean) True if the record is valid and readable

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 \. If you just need to get a catalog item to show its picture or name, consider using GlideRecord to query the sp_cat_item table.

The following example demonstrates how to use getCatalogItem and \ together.

• $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).
  • Returns
    • (Object) An object containing the catalog item variable model, view, sections, pricing and client scripts.

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.

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

(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.

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