3.5 SIF Infrastructure Services

3.5.1 environment

The Consumer Environment Service is the gateway to all other services. It scopes the Consumer's possible interactions with the infrastructure and any Provider Services accessible from it. The Environment Service provides the set of (possibly customized) information the Application needs to interoperate successfully.

SIF_Events are not reported for this object.

environment
Figure 3.5.1-1: environment environment type id fingerprint sessionToken solutionId defaultZone authenticationMethod instanceId userToken consumerName applicationInfo infrastructureServices provisionedZones
 Element/@AttributeCharPrivacy RatingDescriptionType
 environment  

The Consumer Environment Service is the gateway to all other services. It scopes the Consumer's possible interactions with the infrastructure and any Provider Services accessible from it. The Environment Service provides the set of (possibly customized) information the Application needs to interoperate successfully.

 
 
@typeO  environmentTypeType
values:
DIRECT
BROKERED
@
key
idO  uuidType
 fingerprintOnillable="false" 

Unique environment identifier that can be safely shared with others. In order to not compromise security it MUST NOT match the environment's refId, sessionToken, userToken, or applicationKey.

 
xs:token
 sessionTokenOnillable="false"  xs:token
 solutionIdOnillable="false" 

The solution the Application would like to participate in. This is optional only, is advisory, and may be ignored by the Administrator. If processed it may be reflected in the URLs of the infrastructure services which are provided in the consumerEnvironment.

 
xs:token
 defaultZoneOnillable="false"  defaultZoneType
 authenticationMethodOnillable="false" 

Defines the way in which the applicationKey can be used to enforce security.

 
xs:token
 instanceIdOnillable="false"  xs:token
 userTokenOnillable="false"  xs:string
 consumerNameOnillable="false" 

A descriptive name for the application that will be readily identifiable to Zone Administrators if it becomes a Registered Consumer

 
xs:string
 applicationInfoOnillable="false"  applicationInfoType
 infrastructureServicesOnillable="false"  infrastructureServicesType
 provisionedZonesOnillable="false"  provisionedZonesType
Table 3.5.1-1: environment
[ { "environment": { "type": "DIRECT", "id": "B5Fd5DfB-ca3b-162a-5657-dDf31E32cE92", "fingerprint": "f5688c40-97d2-11e6-ae22-56b6b6499611", "sessionToken": "a579ff69-0148-1000-007f-14109fdcaf83", "solutionId": "production", "defaultZone": { "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" } ] } }, "authenticationMethod": "SIF_HMACSHA256", "instanceId": "1", "userToken": "MmZkMjVmODItYjAxMC00NTFiLWFjZTEtNmRjNTI4MWYwZjdlOmhpdHNAbnNpcA==", "consumerName": "Example Consumer", "applicationInfo": { "applicationKey": "Example", "supportedInfrastructureVersion": "3.1", "dataModelNamespace": "http://www.sifassociation.org/datamodel/na/3.3", "transport": "REST", "applicationProduct": { "vendorName": "SIF Association", "productName": "Fingertips Classroom App", "productVersion": "1.0.4", "iconURI": "https://www.sifassociation.org/PublishingImages/SIF%20Assoc%20symbol_LARGE.png " } }, "infrastructureServices": { "infrastructureService": [ { "name": "environment", "value": "https://testharness.sifassociation.org/SIFConnector/AdaptorServer/0f 21cf0b-014c-1000-007f-00505686707f/environment/0f21cf0b-014c-1000-007f00505686707f" }, { "name": "requestsConnector", "value": "https://testharness.sifassociation.org/SIFConnector/AdaptorSer ver/0f21cf0b-014c-1000-007f-00505686707f/requests" } ] }, "provisionedZones": { "provisionedZone": [ { "id": "District", "services": { "service": [ { "name": "students", "contextId": "DEFAULT", "type": "OBJECT", "rights": { "right": [ { "type": "QUERY", "value": "APPROVED" } ] } }, { "name": "sections", "contextId": "DEFAULT", "type": "OBJECT", "rights": { "right": [ { "type": "QUERY", "value": "APPROVED" } ] } } ] } } ] } } } ]
<environment type="DIRECT" id="B5Fd5DfB-ca3b-162a-5657-dDf31E32cE92"> <fingerprint>f5688c40-97d2-11e6-ae22-56b6b6499611</fingerprint> <sessionToken>a579ff69-0148-1000-007f-14109fdcaf83</sessionToken> <solutionId>production</solutionId> <defaultZone 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> </defaultZone> <authenticationMethod>SIF_HMACSHA256</authenticationMethod> <instanceId>1</instanceId> <userToken>MmZkMjVmODItYjAxMC00NTFiLWFjZTEtNmRjNTI4MWYwZjdlOmhpdHNAbnNpcA==</userToken> <consumerName>Example Consumer</consumerName> <applicationInfo> <applicationKey>Example</applicationKey> <supportedInfrastructureVersion>3.1</supportedInfrastructureVersion> <dataModelNamespace>http://www.sifassociation.org/datamodel/na/3.3</dataModelNamespace> <transport>REST</transport> <applicationProduct> <vendorName>SIF Association</vendorName> <productName>Fingertips Classroom App</productName> <productVersion>1.0.4</productVersion> <iconURI>https://www.sifassociation.org/PublishingImages/SIF%20Assoc%20symbol_LARGE.png </iconURI> </applicationProduct> </applicationInfo> <infrastructureServices> <infrastructureService name="environment">https://testharness.sifassociation.org/SIFConnector/AdaptorServer/0f 21cf0b-014c-1000-007f-00505686707f/environment/0f21cf0b-014c-1000-007f00505686707f</infrastructureService> <infrastructureService name="requestsConnector">https://testharness.sifassociation.org/SIFConnector/AdaptorSer ver/0f21cf0b-014c-1000-007f-00505686707f/requests</infrastructureService> </infrastructureServices> <provisionedZones> <provisionedZone id="District"> <services> <service name="students" contextId="DEFAULT" type="OBJECT"> <rights> <right type="QUERY">APPROVED</right> </rights> </service> <service name="sections" contextId="DEFAULT" type="OBJECT"> <rights> <right type="QUERY">APPROVED</right> </rights> </service> </services> </provisionedZone> </provisionedZones> </environment>
Example 3.5.1-1: environment

3.5.2 job

All functional services must use this object design to track state. While Events may be published back to the objects creator, they must not be published to the Consumer when the event was generated based on its request (since results were included in the response). Each functional service should define the expectations of how management of the job is managed for both the Consumer and Provider. For instance, certain optional fields may need to be included in-order-to successfully cause a job to be created.

SIF_Events are reported for this object.

job
Figure 3.5.2-1: job job id name description state stateDescription created lastModified timeout phases initialization
 Element/@AttributeCharPrivacy RatingDescriptionType
 job  

All functional services must use this object design to track state. While Events may be published back to the objects creator, they must not be published to the Consumer when the event was generated based on its request (since results were included in the response). Each functional service should define the expectations of how management of the job is managed for both the Consumer and Provider. For instance, certain optional fields may need to be included in-order-to successfully cause a job to be created.

 
 
@
key
idO  uuidType
 nameM 

The name of the job, e.g. "grading" or "sre".

 
xs:token
 descriptionOnillable="false" 

A description of the job, e.g. "Bowers Elementary School Final Marks"

 
xs:string
 stateOnillable="false" 

The current enumerable state of the job.

 
jobStateType
values:
NOTSTARTED
INPROGRESS
COMPLETED
FAILED
 stateDescriptionOnillable="false" 

A descriptive message elaborating on the current state, e.g. if the current state is "FAILED" the stateDescription may be "Timeout occured".

 
xs:string
 createdOnillable="false" 

The datetime this job was created.

 
xs:dateTime
 lastModifiedOnillable="false" 

The datetime this job was last modified.

 
xs:dateTime
 timeoutOnillable="false" 

The ammount of time after creation before this job is automatically deleted.

 
xs:duration
 phasesOnillable="false" 

The phases that make up this job.

 
phaseCollectionType
 initializationOnillable="false"  initializationType
Table 3.5.2-1: job
[ { "job": { "id": "8dc59f05-4ed6-48e1-9985-f0ef27fed09d", "name": "rolloverStudent", "description": "Rollover Student from year X to year Y", "state": "NOTSTARTED", "stateDescription": "Not Started", "created": "2018-09-03T18:06:56.362-07:00", "timeout": "P30D", "phases": { "phase": [ { "name": "oldYearEnrolment", "states": { "state": [ { "type": "NOTSTARTED" } ] }, "required": true, "rights": { "right": [ { "type": "UPDATE", "value": "APPROVED" } ] }, "statesRights": { "right": [ { "type": "QUERY", "value": "APPROVED" }, { "type": "CREATE", "value": "APPROVED" } ] } }, { "name": "newYearEnrolment", "states": { "state": [ { "type": "NOTSTARTED" } ] }, "required": true, "rights": { "right": [ { "type": "CREATE", "value": "APPROVED" } ] }, "statesRights": { "right": [ { "type": "QUERY", "value": "APPROVED" }, { "type": "CREATE", "value": "APPROVED" } ] } } ] } } } ]
<job id="8dc59f05-4ed6-48e1-9985-f0ef27fed09d"> <name>rolloverStudent</name> <description>Rollover Student from year X to year Y</description> <state>NOTSTARTED</state> <stateDescription>Not Started</stateDescription> <created>2018-09-04T09:06:56.362+08:00</created> <timeout>P30D</timeout> <phases> <phase> <name>oldYearEnrolment</name> <states> <state> <type>NOTSTARTED</type> </state> </states> <required>true</required> <rights> <right type="UPDATE">APPROVED</right> </rights> <statesRights> <right type="QUERY">APPROVED</right> <right type="CREATE">APPROVED</right> </statesRights> </phase> <phase> <name>newYearEnrolment</name> <states> <state> <type>NOTSTARTED</type> </state> </states> <required>true</required> <rights> <right type="CREATE">APPROVED</right> </rights> <statesRights> <right type="QUERY">APPROVED</right> <right type="CREATE">APPROVED</right> </statesRights> </phase> </phases> </job>
Example 3.5.2-1: job

3.5.3 provisionRequest

If an Environment supports self-provisioning Consumers than either this section must initially contain all the rights the Consumer has to all Services in all Zones, or the provisionRequests Infrastructure Service must be present in the Consumer's Environment to allow additional rights to be obtained.

SIF_Events are not reported for this object.

provisionRequest
Figure 3.5.3-1: provisionRequest provisionRequest id completionStatus provisionedZones
 Element/@AttributeCharPrivacy RatingDescriptionType
 provisionRequest  

If an Environment supports self-provisioning Consumers than either this section must initially contain all the rights the Consumer has to all Services in all Zones, or the provisionRequests Infrastructure Service must be present in the Consumer's Environment to allow additional rights to be obtained.

 
 
@
key
idOLow uuidType
@completionStatusO  values:
ACCEPTED
MIXED
REJECTED
 provisionedZonesM 

A specific Zone defined for this environment.

 
provisionedZonesType
Table 3.5.3-1: provisionRequest
[ { "provisionRequest": { "id": "D3E34B39-9D79-4019-8C39-00AA001A1659", "provisionedZones": { "provisionedZone": [ { "id": "SuffolkMiddleSchool", "services": { "service": [ { "type": "OBJECT", "name": "students", "contextId": "DEFAULT", "rights": { "right": [ { "type": "CREATE", "value": "REQUESTED" }, { "type": "UPDATE", "value": "REQUESTED" } ] } } ] } } ] } } } ]
<provisionRequest id="D3E34B39-9D79-4019-8C39-00AA001A1659"> <provisionedZones> <provisionedZone id="SuffolkMiddleSchool"> <services> <service type="OBJECT" name="students" contextId="DEFAULT"> <rights> <right type="CREATE">REQUESTED</right> <right type="UPDATE">REQUESTED</right> </rights> </service> </services> </provisionedZone> </provisionedZones> </provisionRequest>
Example 3.5.3-1: provisionRequest
[ { "provisionRequest": { "id": "4c7cbebc-71e6-11e9-a923-1681be663d3e", "completionStatus": "MIXED", "provisionedZones": { "provisionedZone": [ { "id": "SuffolkMiddleSchool", "services": { "service": [ { "type": "OBJECT", "name": "students", "contextId": "DEFAULT", "rights": { "right": [ { "type": "CREATE", "value": "REJECTED" }, { "type": "UPDATE", "value": "APPROVED" } ] } } ] } } ] } } } ]
<provisionRequest id="4c7cbebc-71e6-11e9-a923-1681be663d3e" completionStatus="MIXED"> <provisionedZones> <provisionedZone id="SuffolkMiddleSchool"> <services> <service type="OBJECT" name="students" contextId="DEFAULT"> <rights> <right type="CREATE">REJECTED</right> <right type="UPDATE">APPROVED</right> </rights> </service> </services> </provisionedZone> </provisionedZones> </provisionRequest>
Example 3.5.3-2: provisionRequest2

3.5.4 queue

The Queues Service supports creation, deletion and querying of Queue (Instance) / Queue Messages Service pairs.

SIF_Events are not reported for this object.

queue
Figure 3.5.4-1: queue queue id polling ownerId name queueUri ownerUri idleTimeout minWaitTime maxConcurrentConnections created lastAccessed lastModified messageCount
 Element/@AttributeCharPrivacy RatingDescriptionType
 queue  

The Queues Service supports creation, deletion and querying of Queue (Instance) / Queue Messages Service pairs.

 
 
@
key
idO  uuidType
 pollingOnillable="false" 

Determines, when no messages are queued, whether the Consumer will have to periodically reissue Polling Requests at timed intervals or can reissue a Polling Request immediately.

 
values:
IMMEDIATE
LONG
 ownerIdCnillable="false" 

The Environment ID of the owning Consumer for which this Queue is buffering messages. It is not specified at Queue create time, but is returned as part of the response to a query operation, and serves to allow an administrative application to identify which application the Queue instance is assigned to.

 
uuidType
 nameOnillable="false" 

A name which the Consumer assigns to the Queue. It is useful for reporting purposes, but is not guaranteed to be unique.

 
xs:token
 queueUriOnillable="false" 

The URI of the Messages Service associated with the Queue instance. This is the endpoint where the 'get next message' requests are issued.

 
xs:anyURI
 ownerUriOnillable="false" 

When present, this contains the URL which the Queue instance will use when it determines the owner needs to be asynchronously alerted that a new message has arrived in the Queue.

 
xs:anyURI
 idleTimeoutOnillable="false" 

Is the maximum time in seconds the Messages Service will wait for a message to arrive, before returning an HTTPS Response of 'no message seen' to the Consumer.

 
xs:unsignedInt
 minWaitTimeCnillable="false" 

indicates the minimum time in seconds that the Consumer should wait after receiving a 'no message seen' response to a previous query, before posting another.

 
xs:unsignedInt
 maxConcurrentConnectionsOnillable="false" 

Number of (properly identified) concurrent connections supported by (the consumer, if suggested, and) the queue.

 
xs:unsignedInt
 createdOnillable="false" 

Time that Queue Instance was Created

 
xs:dateTime
 lastAccessedOnillable="false" 

Time that Queue Instance was last Accessed and a message was dequeued.

 
xs:dateTime
 lastModifiedOnillable="false" 

Time that Queue Instance was last Modified by receiving a new incoming message.

 
xs:dateTime
 messageCountOnillable="false" 

The number of messages currently residing in the Queue.

 
xs:unsignedInt
Table 3.5.4-1: queue
[ { "queue": { "id": "4c7cc042-71e6-11e9-a923-1681be663d3e", "polling": "IMMEDIATE", "name": "StudentConsumer", "maxConcurrentConnections": 3 } } ]
<queue id="4c7cc042-71e6-11e9-a923-1681be663d3e"> <polling>IMMEDIATE</polling> <name>StudentConsumer</name> <maxConcurrentConnections>3</maxConcurrentConnections> </queue>
Example 3.5.4-1: queue Request
[ { "queue": { "id": "e23fce44-7871-48eb-8952-e27733f59b30", "polling": "IMMEDIATE", "ownerId": "545c31ac-85c7-4360-bd63-24d425be1532", "name": "StudentConsumer", "queueUri": "http://localhost:9080/SIF3InfraREST/sif3/queues/e23fce44-7871-48eb-8952-e27733f59b30/messages", "idleTimeout": 0, "minWaitTime": 30, "maxConcurrentConnections": 3, "created": "2019-02-06T17:09:04.421-08:00", "lastAccessed": "2019-02-06T17:09:04.424-08:00", "lastModified": "2019-02-06T17:09:04.424-08:00", "messageCount": 0 } } ]
<queue id="e23fce44-7871-48eb-8952-e27733f59b30"> <polling>IMMEDIATE</polling> <ownerId>545c31ac-85c7-4360-bd63-24d425be1532</ownerId> <name>StudentConsumer</name> <queueUri>http://localhost:9080/SIF3InfraREST/sif3/queues/e23fce44-7871-48eb-8952-e27733f59b30/messages</queueUri> <idleTimeout>0</idleTimeout> <minWaitTime>30</minWaitTime> <maxConcurrentConnections>3</maxConcurrentConnections> <created>2019-02-07T09:09:04.421+08:00</created> <lastAccessed>2019-02-07T09:09:04.424+08:00</lastAccessed> <lastModified>2019-02-07T09:09:04.424+08:00</lastModified> <messageCount>0</messageCount> </queue>
Example 3.5.4-2: queue Response

3.5.5 state

For states updatable by the Consumer, it creates a new state much like it would a single object. The actual result (state or error) is included in the response. Each functional service should define the expectations for which Adaptor is responsible for updating the phase status. NOTE: The "states" collection represented here is reserved for future capabilities.

SIF_Events are reported for this object.

state
Figure 3.5.5-1: state state
 Element/@AttributeCharPrivacy RatingDescriptionType
 state  

For states updatable by the Consumer, it creates a new state much like it would a single object. The actual result (state or error) is included in the response. Each functional service should define the expectations for which Adaptor is responsible for updating the phase status. NOTE: The "states" collection represented here is reserved for future capabilities.

 
Extension of stateCommonType
@idO  uuidType
 typeM 

The type of this State object.

 
phaseStateType
values:
NOTAPPLICABLE
NOTSTARTED
PENDING
SKIPPED
INPROGRESS
COMPLETED
FAILED
 createdOnillable="false" 

The datetime this job was created.

 
xs:dateTime
 lastModifiedOnillable="false" 

The datetime this job was last modified.

 
xs:dateTime
 descriptionOnillable="false" 

A descriptive message ellaborating the condition of this state, e.g. if the state is "FAILED" the stateDescription may be "Timeout occured".

 
xs:string
Table 3.5.5-1: state
[ { "state": { "id": "B8A255AD-DE11-4376-BD54-EAA4C8871F59", "type": "COMPLETED", "created": "2022-07-02T13:43:57.236Z", "lastModified": "2022-07-02T13:43:57.236Z", "description": "All assessments have been scored and are finalized." } } ]
<state id="B8A255AD-DE11-4376-BD54-EAA4C8871F59"> <type>COMPLETED</type> <created>2022-07-02T13:43:57.236Z</created> <lastModified>2022-07-02T13:43:57.236Z</lastModified> <description>All assessments have been scored and are finalized.</description> </state>
Example 3.5.5-1: state

3.5.6 subscription

A Consumer uses the Subscriptions Infrastructure Service to subscribe to Events published by one or more Service Providers.

SIF_Events are not reported for this object.

subscription
Figure 3.5.6-1: subscription subscription id zoneId contextId serviceType serviceSubType messageType serviceName queueId
 Element/@AttributeCharPrivacy RatingDescriptionType
 subscription  

A Consumer uses the Subscriptions Infrastructure Service to subscribe to Events published by one or more Service Providers.

 
 
@
key
idO  uuidType
 zoneIdM  xs:token
 contextIdOnillable="false" 

The unique identity of a context element, which is associated with a Provider of this name and type operating in a Zone with this ID.

 
xs:token
 serviceTypeM 

The type of the service

 
serviceTypeType
values:
UTILITY
OBJECT
FUNCTIONAL
SERVICEPATH
XQUERYTEMPLATE
SERVICE
 serviceSubTypeO 

The subtype of the Service

 
serviceSubTypeType
values:
adminDirective
 messageTypeO 

The type of the message

 
messageTypeType
values:
EVENT
REQUEST
 serviceNameM 

The name of the Service. For utilities, this is fixed to one of the defined set of Utility Service Names. For objects and functions, it is defined by the Data Model.

 
xs:token
 queueIdM 

Specifies which queues you want data associated with this subscription published to.

 
xs:token
Table 3.5.6-1: subscription
[ { "subscription": { "id": "4c7cc1f0-71e6-11e9-a923-1681be663d3e", "zoneId": "auSchoolTestingZone", "contextId": "DEFAULT", "serviceType": "OBJECT", "serviceName": "StudentPersonals", "queueId": "e23fce44-7871-48eb-8952-e27733f59b30" } } ]
<subscription id="4c7cc1f0-71e6-11e9-a923-1681be663d3e"> <zoneId>auSchoolTestingZone</zoneId> <contextId>DEFAULT</contextId> <serviceType>OBJECT</serviceType> <serviceName>StudentPersonals</serviceName> <queueId>e23fce44-7871-48eb-8952-e27733f59b30</queueId> </subscription>
Example 3.5.6-1: subscription Create
[ { "subscription": { "id": "625124a3-1f8f-4d3a-b014-701404d94c6b", "zoneId": "auSchoolTestingZone", "contextId": "DEFAULT", "serviceType": "OBJECT", "serviceName": "StudentPersonals", "queueId": "e23fce44-7871-48eb-8952-e27733f59b30" } } ]
<subscription id="625124a3-1f8f-4d3a-b014-701404d94c6b"> <zoneId>auSchoolTestingZone</zoneId> <contextId>DEFAULT</contextId> <serviceType>OBJECT</serviceType> <serviceName>StudentPersonals</serviceName> <queueId>e23fce44-7871-48eb-8952-e27733f59b30</queueId> </subscription>
Example 3.5.6-2: subscription Create Response

Valid XHTML 1.0 Transitional