Class: SCIMMY.Types.Resource
SCIM Resource Type
Description
Summary:
- Extendable class representing a SCIM Resource Type, which acts as an interface between a SCIM resource type schema, and an app's internal data model.
- Handles incoming requests to read/write/delete a resource, parses any attribute, filter, and sort parameters of a request, and formats responses for consumption by other SCIM clients and service providers.
Usage
Instantiate a new SCIM resource and parse any supplied parameters
new SCIMMY.Types.Resource(idopt, configopt)
Parameters:
Name | Type | Default | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idopt
|
String |
the ID of the requested resource |
|||||||||||||||||||||||||
configopt
|
Object | {} |
the parameters of the resource instance request Properties
|
Properties:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
idopt
|
String |
ID of the resource instance being targeted |
|||||||||||||||
filteropt
|
SCIMMY.Types.Filter |
filter parsed from the supplied config |
|||||||||||||||
attributesopt
|
SCIMMY.Types.Filter |
attributes or excluded attributes parsed from the supplied config |
|||||||||||||||
constraintsopt
|
Object |
sort and pagination properties parsed from the supplied config Properties
|
Members
(abstract, static) endpoint: String
Retrieves a resource's endpoint relative to the service provider's base URL
- Type:
- {String}
(abstract, static) schema: SCIMMY.Types.Schema
Retrieves a resource's core schema
- Type:
- {SCIMMY.Types.Schema}
Methods
(abstract, static) basepath(pathopt) → {SCIMMY.Types.Resource, String}
Sets or retrieves the base path for resolution of a resource's location
Parameters:
Name | Type | Description |
---|---|---|
pathopt
|
String |
the path to use as the base of a resource's location |
Returns:
this resource type class for chaining if path is a string, or the resource's basepath
(static) extend(extension, requiredopt) → {SCIMMY.Types.Resource, void}
Register an extension to the resource's core schema
Parameters:
Name | Type | Description |
---|---|---|
extension
|
SCIMMY.Types.Schema |
the schema extension to register |
requiredopt
|
Boolean |
whether the extension is required |
Returns:
this resource type implementation for chaining
(abstract, static) ingress(handler) → {SCIMMY.Types.Resource}
Sets the method to be called to consume a resource on create
Parameters:
Name | Type | Description |
---|---|---|
handler
|
~IngressHandler |
function to invoke to consume a resource on create |
Returns:
this resource type class for chaining
(abstract, static) egress(handler) → {SCIMMY.Types.Resource}
Sets the method to be called to retrieve a resource on read
Parameters:
Name | Type | Description |
---|---|---|
handler
|
~EgressHandler |
function to invoke to retrieve a resource on read |
Returns:
this resource type class for chaining
(abstract, static) degress(handler) → {SCIMMY.Types.Resource}
Sets the method to be called to dispose of a resource on delete
Parameters:
Name | Type | Description |
---|---|---|
handler
|
~DegressHandler |
function to invoke to dispose of a resource on delete |
Returns:
this resource type class for chaining
(static) describe() → {~ResourceType}
Describe this resource type implementation
Returns:
object describing the resource type implementation
(abstract) read(ctxopt) → {SCIMMY.Messages.ListResponse, SCIMMY.Types.Schema}
Calls resource's egress method for data retrieval. Wraps the results in valid SCIM list response or single resource syntax.
Parameters:
Name | Type | Description |
---|---|---|
ctxopt
|
* |
any additional context information to pass to the egress handler |
Returns:
- A collection of resources matching instance's configured filter, if no ID was supplied to resource constructor.
- The specifically requested resource instance, if an ID was supplied to resource constructor.
(abstract) write(instance, ctxopt) → {SCIMMY.Types.Schema}
Calls resource's ingress method for consumption after unwrapping the SCIM resource
Parameters:
Name | Type | Description |
---|---|---|
instance
|
Object |
the raw resource type instance for consumption by ingress method |
ctxopt
|
* |
any additional context information to pass to the ingress handler |
Returns:
the consumed resource type instance
(abstract) patch(message, ctxopt) → {SCIMMY.Types.Schema}
Retrieves resources via egress method, and applies specified patch operations. Emits patched resources for consumption with resource's ingress method.
Parameters:
Name | Type | Description |
---|---|---|
message
|
Object |
the PatchOp message to apply to the received resource |
ctxopt
|
* |
any additional context information to pass to the ingress/egress handlers |
Returns:
the resource type instance after patching and consumption by ingress method
(abstract) dispose(ctxopt)
Calls resource's degress method for disposal of the SCIM resource
Parameters:
Name | Type | Description |
---|---|---|
ctxopt
|
* |
any additional context information to pass to the degress handler |
Type Definitions
IngressHandler(resource, instance, ctxopt) → {Object}
Handler for ingress of a resource
- Type:
- {function}
Parameters:
Name | Type | Description |
---|---|---|
resource
|
SCIMMY.Types.Resource |
the resource performing the ingress |
instance
|
SCIMMY.Types.Schema |
an instance of the resource type that conforms to the resource's schema |
ctxopt
|
* |
external context in which the handler has been called |
Returns:
an object to be used to create a new schema instance, whose properties conform to the resource type's schema
Examples:
// Handle a request to create a new resource, or update an existing resource
async function ingress(resource, instance, ctx) {
try {
// Call some external controller to update the resource in your database...
if (resource.id) return await ResourceController.update(resource.id, instance, ctx);
// ...or if a resource ID wasn't specified, to create the resource in your database
else return await ResourceController.create(instance, ctx);
} catch (ex) {
switch (ex.message) {
// Be sure to throw a SCIM 404 error if the specific resource wasn't found...
case "Not Found":
throw new SCIMMY.Types.Error(404, null, `Resource ${resource.id} not found`);
// ...or a SCIM 409 error if a database unique constraint wasn't met...
case "Not Unique":
throw new SCIMMY.Types.Error(409, "uniqueness", "Primary email address is not unique");
// ...and also rethrow any other exceptions as SCIM 500 errors
default:
throw new SCIMMY.Types.Error(500, null, ex.message);
}
}
}
EgressHandler(resource, ctxopt) → {Object|Object[]}
Handler for egress of a resource
- Type:
- {function}
Parameters:
Name | Type | Description |
---|---|---|
resource
|
SCIMMY.Types.Resource |
the resource performing the egress |
ctxopt
|
* |
external context in which the handler has been called |
Returns:
-
an object, to be used to create a new schema instance, whose properties conform to the resource type's schema
- Type:
- {Object}
-
an array of objects, to be used to create new schema instances, whose properties conform to the resource type's schema
- Type:
- {Object[]}
Examples:
// Handle a request to retrieve a specific resource, or a list of resources
async function egress(resource, ctx) {
try {
// Call some external controller to retrieve the specified resource from your database...
if (resource.id) return await ResourceController.findOne(resource.id, ctx);
// ...or if a resource ID wasn't specified, to retrieve a list of matching resources from your database
else return await ResourceController.findMany(resource.filter, resource.constraints, ctx);
} catch (ex) {
switch (ex.message) {
// Be sure to throw a SCIM 404 error if the specific resource wasn't found...
case "Not Found":
throw new SCIMMY.Types.Error(404, null, `Resource ${resource.id} not found`);
// ...and also rethrow any other exceptions as SCIM 500 errors
default:
throw new SCIMMY.Types.Error(500, null, ex.message);
}
}
}
DegressHandler(resource, ctxopt)
Handler for degress of a resource
- Type:
- {function}
Parameters:
Name | Type | Description |
---|---|---|
resource
|
SCIMMY.Types.Resource |
the resource performing the degress |
ctxopt
|
* |
external context in which the handler has been called |
Examples:
// Handle a request to delete a specific resource
async function degress(resource, ctx) {
try {
// Call some external controller to delete the resource from your database
await ResourceController.delete(resource.id, ctx);
} catch (ex) {
switch (ex.message) {
// Be sure to throw a SCIM 404 error if the specific resource wasn't found...
case "Not Found":
throw new SCIMMY.Types.Error(404, null, `Resource ${resource.id} not found`);
// ...and also rethrow any other exceptions as SCIM 500 errors
default:
throw new SCIMMY.Types.Error(500, null, ex.message);
}
}
}
ResourceType
An object describing a resource type's implementation
- Type:
- {Object}
Properties:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
id
|
String |
URN namespace of the resource's SCIM schema definition |
|||||||||
name
|
String |
friendly name of the resource's SCIM schema definition |
|||||||||
endpoint
|
String |
resource type's endpoint, relative to a service provider's base URL |
|||||||||
description
|
String |
human-readable description of the resource |
|||||||||
schemaExtensionsopt
|
Object |
schema extensions that augment the resource Properties
|