## 3.6 Utility Services

### 3.6.1 alert

Alerts form a system wide log that can be protected, as it may contain sensitive data. Ideally an Alert should contain as much identifying information about the problem being reported as possible.

SIF_Events are not reported for this object.

Figure 3.6.1-1: alert

| Element/@Attribute | Char | Privacy Rating | Description | Type
--- | --- | --- | --- | --- | ---
| alert |  |  | Alerts form a system wide log that can be protected, as it may contain sensitive data. Ideally an Alert should contain as much identifying information about the problem being reported as possible. |
@ | id | O |  |  | uuidType
| reporter | M |  | External identification of the Application (Consumer or Provider) reporting this Alert. | xs:token
| cause | Onillable="false" |  | External identification of the cause of the Alert. | xs:token
| exchange | M |  | The exchange (or lack of exchange) responsible for generating the Alert. | values: REQUEST RESPONSE EVENT TIMEOUT OTHER
| level | M |  | The level of the Alert. | values: INFO STATECHANGE EVENT WARNING ERROR
| description | Onillable="false" |  | A description of the reason for the Alert. | xs:normalizedString
| messageID | Cnillable="false" |  | If available, the ID of the Message causing the problem. | xs:token
| body | Onillable="false" |  | The internals of the offending message or a more complete description of the information or state change. Usage of the CDATA designation is recommended in order to make the XML contents more readable to humans. | xs:string
| error | Onillable="false" |  | Detailed error results such as a stack trace. | xs:string
| xpath | Onillable="false" |  | An indicator of the specific element that was in error (or contributed to the problem. [NEEDS TO BE CHANGED TO the SIF XPATH TYPE] | xs:normalizedString
| category | Cnillable="false" |  | If the Alert Level is an error, this value must be the SIF 3.0.1 Error Category corresponding to the type of Error being reported | xs:unsignedInt
| code | Cnillable="false" |  | If the Alert Level is an error, this value must be the SIF 3.0.1 Error Code corresponding to the type of Error being reported. | xs:unsignedInt
| internal | Onillable="false" |  | Code internal to the reporter. | xs:token

Table 3.6.1-1: alert
JSON
[ { "alert": { "id": "d0b128e9-fcec-48e9-8ad7-206ded2ddd7f", "reporter": "LovellSIS", "cause": "KleinmanLMS", "exchange": "REQUEST", "level": "WARNING", "description": "Unable to query assessment scores.", "messageID": "24083F7F-6AB0-4912-B7AA-34C05540E2FA" } } ]
XML
<alert id="d0b128e9-fcec-48e9-8ad7-206ded2ddd7f"> <reporter>LovellSIS</reporter> <cause>KleinmanLMS</cause> <exchange>REQUEST</exchange> <level>WARNING</level> <description>Unable to query assessment scores.</description> <messageID>24083F7F-6AB0-4912-B7AA-34C05540E2FA</messageID> </alert>
Example 3.6.1-1: alert

### 3.6.2 codeSet

The Code Set Registry Service provides a way for all legal codes to be defined outside of the SIF Specification while allowing changes (additions and replacements) of external code set values to be easily verified by the recipient so as not to break existing Consumer / Provider interoperability.

SIF_Events are not reported for this object.

Figure 3.6.2-1: codeSet

| Element/@Attribute | Char | Privacy Rating | Description | Type
--- | --- | --- | --- | --- | ---
| codeSet |  |  | The Code Set Registry Service provides a way for all legal codes to be defined outside of the SIF Specification while allowing changes (additions and replacements) of external code set values to be easily verified by the recipient so as not to break existing Consumer / Provider interoperability. |
@ | id | O |  |  | xs:token
xs:minLength | 0
xs:maxLength | 128
| zone | M |  | If this is tied to a specific zone it is specified here, otherwise "environment-global" indicates applicability to all zones in the Environment. | xs:token
| version | M |  | The official major, minor, and revision version of the code set. | versionType
| timestamp | M |  | The date and time of the last change to this code set. So that only updates can be queried efficiently (where applicable). | xs:dateTime
| source | Cnillable="false" |  | URL to an external code set whose values are not (yet) present in the system. | uriType
| codeItems | Onillable="false" |  |  | codeItemsType

Table 3.6.2-1: codeSet
JSON
[ { "codeSet": { "id": "FEDB3FEC-4066-4BC0-882B-DC42CF7C1C0F", "zone": "CamasSchoolDistrict", "version": "1.0", "timestamp": "2022-07-02T14:26:58.762", "source": "https://ceds.ed.gov/element/000328", "codeItems": { "codeItem": [ { "code": "Yes", "value": "Yes", "definition": "An indication that the school has students who are ability grouped for classroom instruction in mathematics or English/reading/language arts.", "action": "ADD", "timestamp": "2022-07-02T14:26:58.762" }, { "code": "No", "value": "No", "action": "ADD", "timestamp": "2022-07-02T14:26:58.762" } ] } } } ]
XML
<codeSet id="FEDB3FEC-4066-4BC0-882B-DC42CF7C1C0F"> <zone>CamasSchoolDistrict</zone> <version>1.0</version> <timestamp>2022-07-02T14:26:58.762</timestamp> <source>https://ceds.ed.gov/element/000328</source> <codeItems> <codeItem> <code>Yes</code> <value>Yes</value> <definition>An indication that the school has students who are ability grouped for classroom instruction in mathematics or English/reading/language arts.</definition> <action>ADD</action> <timestamp>2022-07-02T14:26:58.762</timestamp> </codeItem> <codeItem> <code>No</code> <value>No</value> <action>ADD</action> <timestamp>2022-07-02T14:26:58.762</timestamp> </codeItem> </codeItems> </codeSet>
Example 3.6.2-1: codeSet

### 3.6.3 namespace

The Namespaces Registry contains the set of XML namespace URIs and their corresponding schema location URLs that are currently valid within the Environment.

SIF_Events are reported for this object.

Figure 3.6.3-1: namespace

| Element/@Attribute | Char | Privacy Rating | Description | Type
--- | --- | --- | --- | --- | ---
| namespace |  |  | The Namespaces Registry contains the set of XML namespace URIs and their corresponding schema location URLs that are currently valid within the Environment. |
@ | id | O |  |  | uuidType
| zone | M |  | If this namespace is tied to a specific zone it is specified here. | xs:token
| uri | M |  | The namespace URI of the retrieved URL. | xs:anyURI
xs:maxLength | 2048
| url | M |  | The URL of the specified namespace URI. | xs:anyURI
xs:maxLength | 2048

Table 3.6.3-1: namespace
JSON
[ { "namespace": { "id": "7D818589-364A-467C-800E-7049100A7663", "zone": "CamasSchoolDistrict", "uri": "http://www.sifassociation.org/infrastructure/3.5", "url": "http://specification.sifassociation.org/Implementation/Infrastructure/3.4/XSD/Schema_NoIncludes_Annotated_Strict/SIF_Message.xsd" } } ]
XML
<namespace id="7D818589-364A-467C-800E-7049100A7663"> <zone>CamasSchoolDistrict</zone> <uri>http://www.sifassociation.org/infrastructure/3.5</uri> <url>http://specification.sifassociation.org/Implementation/Infrastructure/3.4/XSD/Schema_NoIncludes_Annotated_Strict/SIF_Message.xsd</url> </namespace>
Example 3.6.3-1: namespace

### 3.6.4 provider

All potentially accessible Services have an entry in the Providers Registry (including the Providers Registry Utility Service itself), although full or even partial Consumer access to that Service is determined by the access rights currently granted in the Consumer's Environment object, and is not guaranteed.

SIF_Events are reported for this object.

Figure 3.6.4-1: provider

| Element/@Attribute | Char | Privacy Rating | Description | Type
--- | --- | --- | --- | --- | ---
| provider |  |  | All potentially accessible Services have an entry in the Providers Registry (including the Providers Registry Utility Service itself), although full or even partial Consumer access to that Service is determined by the access rights currently granted in the Consumer's Environment object, and is not guaranteed. |
@ | id | O |  |  | uuidType
| serviceType | M |  | The generic type of Service being provided. | serviceTypeType values: UTILITY OBJECT FUNCTIONAL SERVICEPATH XQUERYTEMPLATE SERVICE
| serviceName | M |  | The name of the Service or the Service Path being provided. | xs:token
| contextId | M |  | The name of the Service Context being provided. | xs:token
| zoneId | M |  | The Zone in which the Service Context is being provided. | xs:token
| providerName | M |  | The name of the Service Provider as it would be referred to by the administrator of the Zone (ex: RamseySIS). | xs:token
| querySupport | M |  |  | querySupportType
| mimeTypes | Onillable="false" |  |  | mediaTypesType
| endPoint | Cnillable="false" |  | In a Brokered Environment, this element contains the URL where all requests for this Service Provider should be re-invoked by the Connector | protocolType
| supportedRequestTypes | Onillable="false" |  |  | supportedRequestsType

Table 3.6.4-1: provider
JSON
[ { "provider": { "id": "EA6F7130-0F61-42CF-8D9C-68A083060B9F", "serviceType": "OBJECT", "serviceName": "StudentPersonal", "contextId": "DEFAULT", "zoneId": "CamasSchoolDistrict", "providerName": "LovellSIS", "querySupport": { "dynamicQuery": true, "queryByExample": false, "changesSinceMarker": false, "paged": false, "maxPageSize": 1000, "totalCount": true, "applicationProduct": { "vendorName": "Lovell Software", "productName": "LovellSIS", "productVersion": "1.0" }, "adapterProduct": { "vendorName": "Kleinman Computers", "productName": "ScalableREST", "productVersion": "3.5" } }, "mimeTypes": { "mediaType": [ "application/xml", "application/json" ] }, "endPoint": { "location": "http://www.example.com/provider/" }, "supportedRequestTypes": { "supportedRequestType": [ { "requestType": "IMMEDIATE", "operations": { "operation": [ "QUERY", "UPDATE", "DELETE" ] } }, { "requestType": "DELAYED", "operations": { "operation": [ "CREATE" ] } } ] } } } ]
XML
<provider id="EA6F7130-0F61-42CF-8D9C-68A083060B9F"> <serviceType>OBJECT</serviceType> <serviceName>StudentPersonal</serviceName> <contextId>DEFAULT</contextId> <zoneId>CamasSchoolDistrict</zoneId> <providerName>LovellSIS</providerName> <querySupport> <dynamicQuery>true</dynamicQuery> <queryByExample>false</queryByExample> <changesSinceMarker>false</changesSinceMarker> <paged>false</paged> <maxPageSize>1000</maxPageSize> <totalCount>true</totalCount> <applicationProduct> <vendorName>Lovell Software</vendorName> <productName>LovellSIS</productName> <productVersion>1.0</productVersion> </applicationProduct> <adapterProduct> <vendorName>Kleinman Computers</vendorName> <productName>ScalableREST</productName> <productVersion>3.5</productVersion> </adapterProduct> </querySupport> <mimeTypes> <mediaType>application/xml</mediaType> <mediaType>application/json</mediaType> </mimeTypes> <endPoint> <location>http://www.example.com/provider/</location> </endPoint> <supportedRequestTypes> <supportedRequestType> <requestType>IMMEDIATE</requestType> <operations> <operation>QUERY</operation> <operation>UPDATE</operation> <operation>DELETE</operation> </operations> </supportedRequestType> <supportedRequestType> <requestType>DELAYED</requestType> <operations> <operation>CREATE</operation> </operations> </supportedRequestType> </supportedRequestTypes> </provider>
Example 3.6.4-1: provider

### 3.6.5 xquery

This collection defines the entire set of named queries that Consumers may legally issue for execution by Service Providers. A Consumer specifies the ID of a Named XQuery in a Query Request to a specific Service Provider, along with a set of values for any associated script parameters.

SIF_Events are reported for this object.

Figure 3.6.5-1: xquery

| Element/@Attribute | Char | Privacy Rating | Description | Type
--- | --- | --- | --- | --- | ---
| xquery |  |  | This collection defines the entire set of named queries that Consumers may legally issue for execution by Service Providers. A Consumer specifies the ID of a Named XQuery in a Query Request to a specific Service Provider, along with a set of values for any associated script parameters. |
@ | id | C |  | The unique ID of the XQuery Template, which is contained in the Query Request URL when this template is being utilized. "Suggested" by the Consumer issuing the create Request, or pre-set in accordance with the binding requirements of a particular SIF release. This is NOT required to be a UUID, and must be provided as the Service Identifier in every Query URL which invokes this Template. Ex: "StudentSnapshot". | xs:token
| type | M |  | Determines if the query may be sent to a data provider or if it requires the extended XQuery mechanism. | values: SINGULAR FORMULA EXTENDED
| status | M |  | Communicates if the query has been inspected for data hiding and the results of that assessment. | values: PENDING APPROVED DISALLOWED
| qualifier | Onillable="false" |  | If status is DISALLOWED this element optionally contains the reason. | xs:string
xs:minLength | 0
xs:maxLength | 1024
| description | Onillable="false" |  | Human readable description of the XQuery's intended behavior. | xs:string
xs:minLength | 0
xs:maxLength | 1024
| script | M |  | The text of the XQuery which MAY accept parameters. Usage of the CDATA designation is recommended. An empty value indicates the query is implimented wihtout XQuery or its logic is not disclosed | xs:string
xs:minLength | 0
| parameters | M |  |  | parametersType
| returnType | Mnillable="true" |  | The fully qualified name of the root element returned by this service. Example: http://www.sifassociation.org/datamodel/na/3.3:students | xs:anyURI

Table 3.6.5-1: xquery
JSON
[ { "xquery": { "id": "CompanyPODs", "type": "EXTENDED", "status": "APPROVED", "description": "Returns all PODs for the specified company.", "script": "", "parameters": { "parameter": [ { "name": "companyid", "type": "xs:unsignedInt", "default": "63", "description": "The companies unique ID from the Student Data Privacy Consortium (SDPC) registry.", "required": true, "range": { "start": 0, "end": 4294967295 }, "minLength": 1, "maxLength": 10 } ] }, "returnType": "http://www.sifassociation.org/infrastructure/3.5:pods" } } ]
XML
<xquery id="CompanyPODs"> <type>EXTENDED</type> <status>APPROVED</status> <description>Returns all PODs for the specified company.</description> <script /> <parameters> <parameter> <name>companyid</name> <type>xs:unsignedInt</type> <default>63</default> <description>The companies unique ID from the Student Data Privacy Consortium (SDPC) registry.</description> <required>true</required> <range> <start>0</start> <end>4294967295</end> </range> <minLength>1</minLength> <maxLength>10</maxLength> </parameter> </parameters> <returnType>http://www.sifassociation.org/infrastructure/3.5:pods</returnType> </xquery>
Example 3.6.5-1: xquery

### 3.6.6 zone

Zone identifiers are chosen by the administrator and can follow any convention that best meets the needs of the deploying organization. The Zone in which the Service is to be found always qualifies every Consumer request for any Provider Service. Each Service Consumer is assigned a "default" Zone at Registration time, which is used whenever a specific Zone is not explicitly included in one of its Provider Service Requests.

SIF_Events are not reported for this object.

Figure 3.6.6-1: zone

| Element/@Attribute | Char | Privacy Rating | Description | Type
--- | --- | --- | --- | --- | ---
| zone |  |  | Zone identifiers are chosen by the administrator and can follow any convention that best meets the needs of the deploying organization. The Zone in which the Service is to be found always qualifies every Consumer request for any Provider Service. Each Service Consumer is assigned a "default" Zone at Registration time, which is used whenever a specific Zone is not explicitly included in one of its Provider Service Requests. |
@ | id | O |  |  | xs:token
| description | Onillable="false" |  | A short (possibly multi-sentence) description of the Zone | xs:normalizedString
| properties | Onillable="false" |  |  | propertiesType

Table 3.6.6-1: zone
JSON
[ { "zone": { "id": "District", "description": "The zone for the local school district.", "properties": { "property": [ { "name": "email", "value": "john.smith@district.k12.wa.us" }, { "name": "phone", "value": "(360)555-1234" } ] } } } ]
XML
<zone id="District"> <description>The zone for the local school district.</description> <properties> <property name="email">john.smith@district.k12.wa.us</property> <property name="phone">(360)555-1234</property> </properties> </zone>
Example 3.6.6-1: environment