Documentation SDL ServerDocument current as of 10/03/2017 03:35 PM.

Overview

This document provides the information for creating and integrating the

SmartDeviceLink (SDL) server component with the mobile libraries and

vehicle's Head Unit (HU).

The SDL server's main purpose is to curate policy tables composed of rules and

permissions defined by a vehice's OEM. Each vehicle will download it's policy

table and use it to govern SDL behaviors. Additionaly, SDL servers can be used

to gather usage information and provide additional functionality defined by the

OEM.

Example Instance

An instance of the SDL server is hosted at policies.smartdevicelink.com.

Abbreviations and Definitions

Abbreviations used in this document are collected in the table below

A B B R E V I AT I O N M E A N I N G

Policy Tables Overview

Policies are rules enforced by SDL core that configure how the system can and/

or will behave. For example, a policy could prohibit the use of an application

(e.g. Flappy Bird) in a specific type of vehicle. In general, policies are

BT Bluetooth

GUI Graphical User Interface

HMI Human Machine Interface

IVI In Vehicle Infotainment

JSON JavaScript Object Notation

OEM Original Equipment Manufacturer

RPC Remote Procedure Call

SDE Software Development Environment

SDL SmartDeviceLink

SEE Software Engineering Environment

TTS Text To Speech

VDOP Vertical Dilution of Precision

VR Voice Recognition

configured by an OEM (e.g. Ford, GM, Tesla) and stored in their SDL server.

Once configured, all policies for a specific vehicle can be requested in the form

a JSON document called a policy table. Policy tables are downloaded to a

vehicle's head unit where it can be enforced by SDL core.

Example Policy Table

An example policy table is available at policies.smartdevicelink.com. Just click

Perform Request.

Application Policies

An application's permissions and settings are stored in the app_policies

property in a policy table. The application policies are used to grant

applications access to a specific set of features, such as vehicle data and/or

running in the background. Any other application related data, such as user-

consents, can also be stored in application policies as well.

Application ID

Settings for a specific application are stored in the app_policies object as a

property named after the application's unique ID (e.g. "663645645" or any

string of at most 100 characters). The value of this property can be either an

object containing properties listed below or a reference to another sibling

property (e.g. "default" or "device"). In addition, a special value of "null" can be

used to indicate that the application has been revoked.

A P P L I C AT I O NP R O P E RT Y

T Y P E D E S C R I P T I O N

Application HMI Types

An application can be categorized by an HMI type allowing the SDL system

understand how to appropriately handle the application. There are several HMI

types listed below.

keep_context Boolean

When true, allows theapplication to displaymessages even ifanother app enters theforeground (HMI levelFULL).

steal_focus Boolean

When true, allows theapplication to steal theforeground from anotherapplication at will.

priority String Priority level assigned tothe application.

default_hmi String

HMI level given to theapplication following asuccessful registrationwith SDL core.

groups Array of Strings

A list of functionalgroupings theapplication has accessto.

preconsented_groups Array of Strings

List of functionalgroupings that do notrequire a user consentbecause the consent hasalready been given inanother place. (e.g. anapplication EULA)

AppHMIType Array of Strings

List of HMI Types used togroup the applicationinto different containersin an HMI system.

memory_kb String //TODO: Define this

watchdog_timer_ms String //TODO: Define this

certificate String //TODO: Define this

nicknames Array of Strings A list of names theapplication goes by.

A P P L I C AT I O N H M I T Y P E D E S C R I P T I O N

Application HMI Levels

An HMI Level describes the state of an application. Resources are granted to an

application based on its current state. While some resources are granted

automatically to an application in a specific HMI Level, many can be controlled

by the policy table.

BACKGROUND_PROCESS //TODO: Add description

COMMUNICATION //TODO: Add description

DEFAULT //TODO: Add description

INFORMATION //TODO: Add description

MEDIA //TODO: Add description

MESSAGING //TODO: Add description

NAVIGATION //TODO: Add description

SOCIAL //TODO: Add description

SYSTEM //TODO: Add description

TESTING //TODO: Add description

L E V E L VA LU ES H O RTD E S C R I P T I O N

Default

A default application configuration can be stored in the app_policies object as

a property named default. This property's value is an object containing any

valid application property excluding certificate and nicknames.

Device

// TODO: What is this used for?

Full 0

An application istypically in Full when itis displayed in the HMI.In Full an applicationhas access to the HMIsupported resources,e.g. UI, VR, TTS, audiosystem, and etc.

Limited 1

An application istypically placed in Limited when a message ormenu is displayed Limited to restrict it'spermissions.

Background 2

An application istypically in Background when it is not beingdisplayed by the HMI.When in Backgroundan application can sendRPCs according to thePolicy Table rules.

None 3

When placed in Nonean application has noaccess to HMI supportedresources.

Example

An example of how the Application Policy portion of a policy table might look.

"app_policies": { "default": { "keep_context": true, "steal_focus": true, "priority": "NONE", "default_hmi": "NONE", "groups": [ "Base-1" ], "preconsented_groups": [ "" ], "AppHMIType": [ "" ], "memory_kb": 5, "watchdog_timer_ms": 55 }, "device": { "keep_context": true, "steal_focus": true, "priority": "NONE", "default_hmi": "NONE", "groups": [ "Base-2" ], "preconsented_groups": [ "" ] }, "pre_DataConsent": { "keep_context": true, "steal_focus": true, "priority": "NONE", "default_hmi": "NONE", "groups": [ "BaseBeforeDataConsent" ], "preconsented_groups": [ "" ], "AppHMIType": [ "" ], "memory_kb": 5, "watchdog_timer_ms": 55 }, "663645645": "null", "773692255": "default", "584421907": { "nicknames": [ "Awesome Music App" ], "keep_context": true, "steal_focus": true, "priority": "NONE", "default_hmi": "NONE", "groups": [ "VehicleInfo-1" ], "preconsented_groups": [ "" ], "AppHMIType": [ "" ], "memory_kb": 5, "watchdog_timer_ms": 55, "certificate": "" }}

Consumer Friendly Messages

There are certain scenarios when the SDL system needs to display a message

to the user. Some examples are when an error occurs or an application is

unauthorized. These messages can include spoken text and text displayed to a

user in multiple languages. All of this information is stored in the

consumer_friendly_messages property.

Messages

All messages are given a unique name (e.g. "AppUnauthorized" or

"DataConsent") and stored as an object in the consumer_friendly_messages

object's messages property.

Language

Since each message should support multiple languages, each message object

will contain a property named languages. Language properties are name by

combining the ISO 639-1 language code and the ISO 3166 alpha-2 country

code. For example, messages for English speaking citizens of the United

States would be under the key en-us.

Message Text

Inside each language object is the data to be read or spoken by the SDL

system. The data is organized in the following properties.

M E SS A G E T E X TP R O P E RT Y

T Y P E D E S C R I P T I O N

Version

The version property in the consumer_friendly_messages object defines the

current version of all the messages. It is used during a poilcy table update to

determine wether or not the consumer friendly messages need to be updated.

The version must be in the format ###.###.### .

Example

An example of how the Consumer Friendly Messages portion of a policy table

might look.

tts StringText that can be readaloud by the SDLsystem.

line1 StringFirst line of text to bedisplayed on the headunit.

line2 StringSecond line of text to bedisplayed on the headunit.

"consumer_friendly_messages": { "version": "001.001.015", "messages": { "AppUnauthorized": { "languages": { "de-de": { "tts": "Diese Version von %appName% ist nicht autorisiert und wird nicht mit SDL funktionieren.", "line1": "nicht autorisiert" }, "en-ie": { "tts": "This version of %appName% is not authorized and will not work with SDL.", "line1": "not authorized" }, "en-us": { "tts": "This version of %appName% is not authorized and will not work with SDL.", "line1": "Not Authorized" } } }, "DataConsent": { "languages": { "en-us": { "tts": "To use mobile apps with SDL, SDL may use your mobile device's data plan....", "line1": "Enable Mobile Apps", "line2": "on SDL? (Uses Data)" } } } }}

Device Data

Information about each device that connects to SDL core is recorded in the

policy table. This information is used to persist configurations for the head unit

based on the device connected.

Device Specific Information

Devices are identified in the policy table using a unique identifier. Device

unique identifier(s) are either a bluetooth mac address or USB serial address

irreversibly encrypted/hashed using SHA-256. Information about a specific

device is stored using its unique identifier as a key. The following properties

describe the information stored.

P R O P E RT Y T Y P E D E S C R I P T I O N

hardware StringType and/or name of thehardware. (e.g. iPhone4S)

max_number_rfcom_ports Number Number of RFCOM ports

supported by the device.

firmware_rev String Device's firmwareversion

os String Operating system. (e.g.iOS or Android)

os_version String Device's operatingsystem version.

carrier StringThe mobile phone'scarrier. (e.g. Verizon orAT&T)

User Consents

Whether or not an SDL user has given permission for a feature can be stored

for each device and application connected to a vehicle's head unit. For

example, a user may consent to allowing SDL to use their phone's cellar data to

download policy table updates. These consent records are stored in the

user_consent_records property.

Device

User consent(s) for a device are stored in a property named device in the

user_consent_records object. The value of this property is an object with the

following properies:

U S E R C O N S E N TR E C O R D P R O P E RT Y

T Y P E D E S C R I P T I O N

// TODO: Input and timestamp need a better description and clarification.

Application

User consent(s) can also be saved per application on a device under a property

named after its Application ID. The value of this property is an object with the

same user consent record properties as device above.

consent_groups ObjectA listing of SDL featuresthat are accepted ordeclined.

input String Accepted values are"GUI" or "VUI"

time_stamp String A timestamp in ISO 8601format.

Example

An example of how the Device Data portion of a policy table might look.

Functional Groupings

Before an application can use each feature offered by SDL it must first be

granted permission to do so in the policy table. Each feature may require

"device_data": { "UEI17A73JH32L41K32JH4L1K234H3K4HUU40DAS7F970": { "hardware": "iPhone 4S", "max_number_rfcom_ports": 25, "firmware_rev": null, "os": "iOS", "os_version": "5", "carrier": "AT&T", "user_consent_records": { "device": { "consent_groups": { "DataConsent-1": true }, "input": "VUI", "time_stamp": "4/24/2012 12:30:00 PM" }, "584421907": { "consent_groups": { "Location-1": true, "DrivingData-1": false }, "input": "VUI", "time_stamp": "3/26/2012 10:41:00 AM " } } }}

several RPCs with specific HMI level permission, as well allowed parameters

and other information. In order to avoid duplicating this data for each

application, SDL instead uses functional groupings. A functional grouping is

simply a group of RPC messages and parameters with specific HMI permissions

and allowed parameters. So for example, if an application named Torque

wanted access to vehicle data you would simply add the VehicleData

functional group to Torque's allowed policies.

Functional Group

Each functional group is given a unique name (e.g. BasicVehicleData) that is

used to reference that group from anywhere within the Policy Table. Each

functional group may contain the following properties.

F U N C T I O N A L G R O U PP R O P E RT Y

T Y P E D E S C R I P T I O N

RPCS

Each RPC in the rpcs property has a unique name that represents an existing

RPC (e.g. AddSubMenu). In each RPC object there may be the following

properties.

rpcs Object

A list of RemoteProcedure Calls andtheir configurations forthe current functionalgrouping.

user_consent_prompt String

References a consumerfriendly messageprompt that is requiredto use the RPC. If thisfield is not present, thena consumer friendlymessage prompt is notrequired.

P R O P E RT Y T Y P E D E S C R I P T I O N

Example

An example of how the Functional Groupings portion of a policy table might

look.

hmi_levels Array

An ordered list of HMIlevels that anapplication is allowed touse a the RPC commandin.

parameters Array

A list of allowedparameters that theapplication can use withthe RPC command.

"functional_groupings": { "Base-1": { "rpcs": { "AddCommand": { "hmi_levels": [ "BACKGROUND", "FULL", "LIMITED" ] }, "AddSubMenu": { "hmi_levels": [ "BACKGROUND", "FULL", "LIMITED" ] }, "Alert": { "hmi_levels": [ "FULL", "LIMITED" ] }, } }, "VehicleInfo-1": { "user_consent_prompt": "VehicleInfo", "rpcs": { "GetVehicleData": { "hmi_levels": [ "BACKGROUND", "FULL", "LIMITED" ], "parameters": [ "engineTorque", "externalTemperature", "fuelLevel", "fuelLevel_State", "headLampStatus", "instantFuelConsumption", "odometer", "tirePressure", "vin", "wiperStatus" ] }, }

Module Config

The module configuration property contains information used to configure SDL

core for use on the current vehicle.

Notifications

There is a limit for the number of notifications that can be displayed per priority

level. The limit is instead based on notifications per minute. You can configure

these in the notifications_per_minute_by_priority property. The following

are the available priority levels.

P R O P E RT Y T Y P E D E S C R I P T I O N

}}

EMERGENCY NumberNumber of emergencynotifications that can bedisplayed per minute.

COMMUNICATION Number

Number ofcommunicationnotifications that can bedisplayed per minute.

NAVIGATION NumberNumber of navigationnotifications that can bedisplayed per minute.

NONE Number

Number of notificationswithout a priority thatcan be displayed perminute.

NORMAL Number

Number of notificationswith a normalprioritythat can bedisplayed per minute.

voiceCommunication Number

Number of voicecommunicationnotifications that can bedisplayed per minute.

Policy Table Update Configurations

Periodically changes will be made to a policy table, either by the server or core.

This means core should check for and perform a policy table updates, which

synchronizes the local and server policy tables. You can configure when core

will check using the following configurations.

P R O P E RT Y T Y P E D E S C R I P T I O N

Preloaded Policy Tables

SDL core can use a predefined policy table located locally on the vehicle's head

unit. This is present to initially configure core as well as to enable the storage of

vehicle data before a policy update has occurred.

// TODO: Is this correct?

P R O P E RT Y T Y P E D E S C R I P T I O N

exchange_after_x_ignition_cycles Number Update policies after a

number of ignitions.

exchange_after_x_kilometers Number

Update policies after anumber of kilometerstraveled.

exchange_after_x_days Number Update policies after anumber of days.

preloaded_pt BooleanWhen true, core will usethe local copy of thepolicy table.

Server Requests

All requests made directly by core or by proxy can be configured using the

following attributes.

P R O P E RT Y T Y P E D E S C R I P T I O N

Service Types

// TODO: Define these.

Vehicle Information

Vehicle identification information is stored in the module configuration portion

of the policy table.

timeout_after_x_seconds NumberElapsed seconds until apolicy update requestwill timeout.

endpoints Object

Contains a list of servicetypes that may containa default or app-specificarray of serverendpoints.

seconds_between_retries Array A list of seconds to wait

before each retry.

P R O P E RT Y T Y P E D E S C R I P T I O N

Example

An example of how the Module Config portion of a policy table might look.

vehicle_make String Manufacturer of thevehicle.

vehicle_model String Model of a vehicle.

vehicle_year String Year the vehicle wasmade.

"module_config": { "endpoints": { "0x07": { "default": [ "http://policies.telematics.ford.com/api/policies" ], } }, "exchange_after_x_ignition_cycles": 100, "exchange_after_x_kilometers": 1800, "exchange_after_x_days": 30, "notifications_per_minute_by_priority": { "EMERGENCY": 60, "NAVIGATION": 15, "voiceCommunication": 10, "COMMUNICATION": 6, "NORMAL": 4, "NONE": 0 }, "seconds_between_retries": [ 1, 5, 25, 125, 625 ], "timeout_after_x_seconds": 60, "vehicle_make": "Ford", "vehicle_model": "F-150", "vehicle_year": "2015",}

Module Meta

Language and Country

The current language and regional settings can be configured using the

following properties.

P R O P E RT Y T Y P E D E S C R I P T I O N

Module Version

The current version of the vehicle's module should be stored in the following

property.

P R O P E RT Y T Y P E D E S C R I P T I O N

Policy Table Update

Information about when a policy table update has last taken place is stored in

the following properties.

language String

Current systemlanguage. ISO 639-1combined with ISO 3166alpha-2 country code.

wers_country_code String //TODO: What is this.

ccpu_version String Software version for themodule running core.

P R O P E RT Y T Y P E D E S C R I P T I O N

Vehicle Data

Additional vehicle information is stored in the module meta property.

P R O P E RT Y T Y P E D E S C R I P T I O N

Example

An example of how the Module Meta portion of a policy table might look.

pt_exchanged_at_odometer_x Number

Marks the odometerreading in kilometers atthe time of the lastsuccessful policy tableupdate.

pt_exchanged_x_days_after_epoch Number

Marks the time of thelast successful policytable update.

ignition_cycles_since_last_exchange Number

Number of ignitioncycles since the lastpolicy table update.

vin String The vehicle's uniqueidentification number.

"module_meta": { "ccpu_version": "4.1.2.B_EB355B", "language": "en-us", "wers_country_code": "WAEGB", "pt_exchanged_at_odometer_x": 1903, "pt_exchanged_x_days_after_epoch": 46684, "ignition_cycles_since_last_exchange": 50, "vin": "1FAPP4442VH100001"}

Usage and Errors

Some usage and error statistics are collected to help developers debug

problems and improve SDL. The information does not contain user information

and is very small as to use as little mobile data as possible. This data is sent to

the SDL server when performing a policy table update.

Application Errors

Errors and usage statistic that occur while an applciation is in use or are related

to an application are recorded. The following properties are tracked in a

property named after the application's ID.

P R O P E RT Y T Y P E D E S C R I P T I O N

app_registration_language_gui String

Language used toregister the applicationusing GUI.

app_registration_language_vui String

Language used toregister the applicationusing VUI.

count_of_rejected_rpcs_calls Number

Count of RPC calls thatwere rejected becauseaccess was not alloweddue to a policy.

count_of_rejections_duplicate_name Number

Number of times anapplication registrationuses a name which isalready registered in thecurrent ignition cycle.

count_of_rejections_nickname_mismatch Number

Number of times an appis not allowed to registerbecause it's registrationdoes not match one ofthe app-specific policynicknames.

count_of_rejections_sync_out_of_memory Number

Number of times anapplication is notallowed to registerbecause the vehiclemodule is out ofmemory (as defined incount_of_sync_out_of_memory).

count_of_removals_for_bad_behavior Number

The module has criteriafor identifyingunacceptably badapplication behavior.This tracks the numberof times that distinctionleads the module tounregister anapplication.

count_of_rfcom_limit_reached Number

Number of times themaximum number ofrfcom channels are usedon a device by theapplication.

count_of_rpcs_sent_in_hmi_none Number

Number of times anapplication tried to usean RPC (notunregisterAppInterface)in the HMI NONE state.Counts the number ofconflicts with the built-in/hardcoded restrictionfor HMI_STATE=NONE.

count_of_run_attempts_while_revoked Number

Incremented when theuser selects a revokedapplication from theSYNC HMI menu.

P R O P E RT Y T Y P E D E S C R I P T I O N

General Errors

Some basic usage and error counts are stored in the following properties.

P R O P E RT Y T Y P E D E S C R I P T I O N

count_of_user_selections Number

Number of times a userselected to run the app.Increment one when appstarts via Mobile AppsMenu or VR. Incrementone the first time theapp leaves it'sdefault_hmi forHMI_FULL, as in theresuming app scenario.Do not incrementanytime an app comesinto HMI_FULL. Do notincrement when cyclingsources. For all 3scenarios, bothsuccessful andunsuccessful app startsshall be counted.

minutes_in_hmi_background Number

Number of minutes theapplication is in the HMIbackground state.

minutes_in_hmi_full NumberNumber of minutes theapplication is in the HMIfull state.

minutes_in_hmi_limited NumberNumber of minutes theapplication is in the HMIlimited state.

minutes_in_hmi_none NumberNumber of minutes theapplication is in the HMInone state.

count_of_iap_buffer_full NumberNumber of times the iOSaccessory protocolbuffer is full.

count_of_sync_reboots Number Number of times thehead unit has rebooted.

count_sync_out_of_memory Number

Number of times theCCPU has run out ofmemory.

Example

An example of how the Usage and Error portion of a policy table might look.

Policy Table Update

Periodically changes will be made to a policy table, either by an SDL server or

SDL core. In order to synchronize the two tables a policy table update must be

performed. An update is triggered by core by either an application connecting

"usage_and_error_counts": { "count_of_iap_buffer_full": 1, "count_of_sync_reboots": 123, "count_sync_out_of_memory": 3, "app_level": { "584421907": { "app_registration_language_gui": "en-us", "app_registration_language_vui": "en-us", "count_of_rejected_rpcs_calls": 9, "count_of_rejections_duplicate_name": 2, "count_of_rejections_nickname_mismatch": 1, "count_of_rejections_sync_out_of_memory": 0, "count_of_removals_for_bad_behavior": 6, "count_of_rfcom_limit_reached": 1, "count_of_rpcs_sent_in_hmi_none": 7, "count_of_run_attempts_while_revoked": 0, "count_of_user_selections": 7, "minutes_in_hmi_background": 123, "minutes_in_hmi_full": 123, "minutes_in_hmi_limited": 456, "minutes_in_hmi_none": 456 } }}

for the first time or by one of the policy table update configurations or by a

user's request. When requesting a policy table update, core sends its current

policy table, called a policy table snapshot, to the server. The server records

any aggregate usage data as needed or designed, then responds to the request

with a policy table update that contains the latest module config, functional

groupings, application policies, and consumer friendly messages. The

application policies section will only contain information for the current list of

applications in the received policy table snapshot. In addition, the consumer

friendly messages will only be included if an update is required, meaning the

received policy table snapshot has an older version than the server.

SEQUENCE DIAGRAM

Policy Table Update Sequence Diagram

Policy Table Update Sequence DiagramSteps

1. A policy table update is triggered by SDL core and a snapshot of the

current policy table is created. The snapshot includes the entire local

policy table with one exception. Only the version number property of the

consumer friendly messages section is included in the snapshot.2. An OnSystemRequest RPC is created with a request type of proprietary.

The RPC contains a policy table snapshot in binary and a URL from one of

the endpoints defined in the module config. In addition, HTML request

headers can be present to be used when making the request.3. The RPC's data is, optionally, encrypted using an asynchronous key that

only the SDL server can decrypt. The URL and headers are not encrypted

since they are required by the mobile library to forward the request to the

SDL server.4. The RPC is then sent to the mobile library.

View Diagram

5. The mobile library will ignore the request body containing the policy table

snapshot, because it is marked as proprietary, and will forward the

request to the URL included in the OnSystemRequest RPC. If the request

fails to send then the mobile library will attempt to retry using the

configuration specified in the module config.6. When the server receives the policy table update request it will first

lookup the module in the server's database using a unique identifier. If the

module is not found an error will be retured in the server's response.7. If the policy table snapshot is encrypted, then the server will use the

symmetric key found in the module's database record, the one we just

looked up, to decrypt the policy table snapshot. If the data cannot be

decrypted, then the data is not from a trusted source and an error is

returned in the server's response.8. The aggregate usage data and vehicle data in the received policy table

snapshot is recorded to the server's database. Typically Usage and Error

Counts, Device Data, and Module Meta contain data to be recored.9. A policy table update is created based on the received policy table

snapshot. Note that only applications listed in the policy snapshot will be

included in the update. In addition, if the consumer friendly messages

version number is lower than the version available on the server, then the

updated consumer friendly messages will also be included in the policy

update.10. Then the policy table update is, optionally, encrypted using an

asynchronous key from the module record we previously looked up.11. Finally the policy table update is returned in the response to the policy

update request.12. The mobile library then forwards the server's response to core using a

SystemRequest RPC message.13. After being received by core the response body, if encrypted, is decrypted

using an asymetric key. If the body cannot be decrypted, then the data is

not from a trusted source and an error is returned to the mobile library

using a SystemRequestResponse RPC.14. The policy table update is applied by replacing the following fields in the

local policy table with the fields from the policy table update: module

config, functional groupings, and application policies. In addition, if the

consumer friendly messages section of the policy table update contains a

messages subsection, then the entire consumer friendly messages

portion of the local policy table will be replaced with the values from the

policy table update.15. If the response is valid and everything updates ok, then success is

returned to the mobile library using a SystemRequestResponse RPC.

Download the project to your current directory.

The most up-to-date branch is v2. Switch to it.

The new version of the policy server requires a SQL database. Currently the

only supported implementation is PostgreSQL, but you can create a module for

your favorite database. This guide will not cover how to get one running.

Once you set up a database (locally or remotely) you'll need to supply the

policy server with some environment variables. This policy server uses the

dotenv module, meaning you can write all your environment variables in a

.env file located in the server directory. The policy server will load the

variables at server/.env . .env files will not be tracked by Git.

Here are the environment variables that will most likely be used:

• POLICY_SERVER_PORT: The port which the server runs on. It is optional

and the default is 3000.• SHAID_PUBLIC_KEY: A public key given to you through the developer

portal that allows access to SHAID endpoints.• SHAID_SECRET_KEY: A secret key given to you through the developer

portal that allows access to SHAID endpoints.

git clone https://github.com/smartdevicelink/sdl_server.gitcd sdl_server

git checkout v2

• STAGING_PG_USER: The name of the user to allow the server access the

database (staging mode)• STAGING_PG_DATABASE: The name of the database where policy and app

data is stored (staging mode)• STAGING_PG_PASSWORD: The password used to log into the database

(staging mode)• STAGING_PG_HOST: The host name or IP address of the database (staging

mode)• STAGING_PG_PORT: The port number of the database (staging mode)• PRODUCTION_PG_USER: The name of the user to allow the server access

the database (production mode)• PRODUCTION_PG_DATABASE: The name of the database where policy and

app data is stored (production mode)• PRODUCTION_PG_PASSWORD: The password used to log into the

database (production mode)• PRODUCTION_PG_HOST: The host name or IP address of the database

(production mode)• PRODUCTION_PG_PORT: The port number of the database (production

mode)

Once these environment variables are set, initialize the database. The staging

database should be given the same name set in STAGING_PG_DATABASE. For

the production database, use the name set in PRODUCTION_PG_DATABASE

Using the createdb program that comes with the installation of PostgreSQL, for

example:

createdb policy_server_staging

The policy server comes with migration scripts that can be run using npm

scripts. You can see a list of all the possible scripts by looking in server/

package.json , but these are the most important ones:

• start-pg-staging: Runs the migration up script which initializes data in the

database, sets the environment to staging and starts the policy server• start-pg-production: Runs the migration up script which initializes data in

the database, sets the environment to production and starts the policy

server• db-migrate-reset-pg-staging: Runs the migration down script which drops

all the data and tables in the staging database

Run the following command to finalize set up and start the server in staging

mode.

npm run-script start-pg-staging

Now you have a server running!

These are the API routes that the policy server exposes.

GET /api/v1/request

Queries SHAID for updated application information. This route automatically

gets called on server start up.

WebHook integration is planned for future releases so that this updating

application process can be automatic.

POST /api/v1/staging/policy

This is the route sdl_core's default policy table should use when requesting a

policy table update.

Given a "shortened" policy table, the policy server will use that information to

automatically construct a full policy table response and return it to the

requester. Only a staging route is accessible because there is currently no

difference between a staging mode and production mode policy request.

Changes are also planned in the future for these routes.

It will be helpful to understand what the policy server is doing behind the

scenes before modifying the source code. This section will describe what tasks

the policy server does under certain conditions.

On Startup

One of the first things the policy server does is load all the custom modules

that are defined in the server/config.js file. There are currently four types of

customizable modules that the server loads:

• server/custom/loggers: Logger modules define how messages from the

policy server are handled. The default logger is winston and logs

everything to server/policy_logs.log as well as color codes logs in the

console with timestamps.• server/custom/databases: Database modules allow the policy server to

connect to a database of the developer's choice, under the constraint that

it is a SQL database. The default module is postgres which uses

environment variables specified in the installation page to forward SQL

queries to a pool of clients connected to the database. • server/custom/data-collectors: These modules are a source of information

for the policy server, such as country data, permissions, and HMI levels.

The default module is shaid and is vital for the functional operation of the

server, as it talks to SHAID for relevant information. Additional modules

can be created and chained together to provide more information than

what the shaid module currently has.• server/custom/policy-builders: This is the most versatile custom module.

These modules are responsible for constructing the policy table. The

default module implements some required functions that instruct it to

create certain pieces of the policy table. The policy server will take care of

storing and retrieving that data when necessary.

After loading, the policy server will undergo an update cycle. An update cycle

synchronizes information between data sources like SHAID and the policy

server. Examples include country information, and permissions.

After the update cycle, functional groups are generated or updated. Functional

groups contain permissions that get assigned to application IDs in order to

permit apps to using data. These functional groups are generated with the help

of the policy-builder modules.

After functional groups are updated, 3 of 4 parts of the policy table are

generated and stored in memory: the module config object, the consumer

friendly messages object, and the functional groups object. These objects are

not expected to change throughout the lifetime of the policy server. If changes

are made that would cause any of those three objects to be changed, then the

policy server needs to be restarted for those changes to take effect.

Finally, the function invoked by /api/v1/request is hit which will update

application information by querying SHAID for all applications. In future

releases WebHooks will be used in replacement to put less load on SHAID and

the policy server.

On Evaluate Application Request

Every application that the policy server receives undergoes an evaluation. If

there is information in the application that the policy server doesn't know about

(ex. A country code that isn't recorded in the policy server's database) then one

attempt will be made to update information. If after the update there still is

information unknown about the application it will not be stored.

Otherwise, the application request will be set to a PENDING approval state and

stored in the database if its timestamp is later than the timestamp of the same

app uuid stored in the database.

On Policy Table Update

If the /api/v1/policy endpoint gets hit then the requester wants a policy table

update. First, basic validation happens to make sure the format of the request

is correct. Then, the policy table is constructed and sent back as a response.

The consumer friendly messages, the module config, and the functional groups

are already built, so there's no extra computation needed there. The app

policies object needs extra logic because that object is where applications are

given or denied permissions.

For now, all applications are given permissions by default only if their uuid is

found in the policy server database. The approved uuids are then looked up in

the database and the full application is reconstructed. Next, the app policies

object is constructed using the information from the applications. The policy

server hands off this work to the policy-builders module. When finished, the

policy server sends the full policy table as a response.

The policy server relies on custom modules to do work that the policy server

cannot do because otherwise the server will make some unnecessary

assumptions that may not make sense for some developers. Splitting up work

into separate modules and allowing customization of those modules is what

makes the policy server so flexible. There are some basic restrictions and

functions required to implement for custom modules to work, and that will be

covered here.

Loggers

Only two named functions need to be exported in an object for a valid

implementation: info and error . info accepts a string as its first parameter

and is used to log non-error messages using the string. error accepts a string

and is used for logging error messages using the string. Check the default

winston module for an example.

Databases

Only slightly more complicated than the logger, the export should be just a

function with a logger object as the argument. This object is the same object as

the one exported in the custom logger module, so info and error can be

invoked on it. In addition to exporting a function, it must return an object with a

function in it named sqlCommand :

query is the SQL string to execute, and callback is the function to invoke

when sqlCommand is complete. Check out the default postgres module for

an example implementation

Data Collectors

Similar to the database module, this module must export a function where a

logger will be passed in as an argument. The function must return an object of

the following structure:

Note that the function signature is different than the one found in the default

shaid module. This is because shaid is the first data collector to be invoked,

return { sqlCommand: function (query, callback) { }}

return { getAppRequests: function (appRequests, next) { }, getHmiLevels: function (hmiLevels, next) { }, getCountries: function (countries, next) { }, getCategories: function (categories, next) { }, getRpcPermissions: function (rpcPermissions, next) { }, getVehicleDataPermissions: function (vehicleDataPermissinons, next) { }};

and therefore no data can be passed to it. When next is called, the data from

shaid will be passed to any other data collectors that have been defined in

config.js . Those other modules can then append additional information and

pass it to the next modules.

next is a callback function that accepts two parameters. The first parameter is

an error of some sort. If it is defined, the policy server will see that as an error

that happened. The second parameter is the data that should be passed

depending on the function. If a custom module doesn't wish to modify anything

passed to it for say, getCategories , then it should invoke next like so: next

(null, categories) .

To see the format of each type of data, check out the shaid module, or look

here for responses that come from SHAID.

Policy Builders

A function needs to be exported, and a logger module will be passed in as an

argument. Here's the required return object:

Full explanations are given in the source code as to what each of these

functions require and what they need to return, but here is a summary:

initiateFunctionalGroups : Invoked first, and only when the policy server starts

return { initiateFunctionalGroups: function () { }, createGroupPermissions: function () { }, modifyFunctionalGroupObject: function (funcGroupObj) { }, preRunAppPolicyObject: function (appPolicy) { }, createAppPolicyObject: function (appObj) { }};

up and is beginning to build functional groups. This function should return a

"skeleton" of what the functional groups should be

createGroupPermissions : Invoked secondly, and only on server start up. For

every functional group defined in initiateFunctionalGroups , define permissions

that the functional group permits.

modifyFunctionalGroupObject : Invoked thirdly, and only on server start up.

Final edits to the functional group happen here, and full control is given over

what can be edited. For example, in the default policy builder module this

function is used to add HMI levels to each functional group, which is a vital

step.

preRunAppPolicyObject : Invoked when a policy table update happens. Here is

where defaults can be set up before iterating through each approved

application.

* createAppPolicyObject : Invoked when a policy table update happens. Here is

where functional groups are assigned to applications, and which functional

groups are assigned may depend on the permissions those applications asked

for. After this function is invoked for every approved application, the policy

table is constructed and sent to the requester.

Migration scripts are important because they automate inserting and removing

data from the database. Therefore, the server should always have data inserted

and removed through migration up and down scripts. The package.json file

has sample scripts which run those migrations, but if those migrations need to

be edited, then go to the folder server/migrations/sqls .

These scripts contain set up and tear down SQL statements. It is also the

source of the module config object and consumer friendly messages object. The

migration up file needs to be modified to edit either of those objects and the

server will need to be restarted for those changes to take effect.

The migration script also contains all the table and type definitions at the top of

the file. These can be changed like everything else about the policy server, but

remember that the policy server depends on the structure of this information

being the same; the server will likely crash if changes are made to these table

definitions. Changes will need to be made to the internal modules of the policy

server, which are located in server/app .