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
|
~ListConstraints
|
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
(abstract, static) extend(extension, requiredopt) → {SCIMMY.Types.Resource}
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() → {~ResourceDescription}
Describe this resource type implementation
Returns:
object describing the resource type implementation
(async, 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:
the specifically requested resource instance, if an ID was supplied to resource constructor, or collection of resources matching instance's configured filter.
(async, 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
(async, 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 Properties
|
||||||
ctxopt
|
*
|
any additional context information to pass to the ingress/egress handlers |
Returns:
the resource type instance after patching and consumption by ingress method
(async, 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) → {Record<String, *>}
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) → {Record<String, *>|Record<String, *>[]}
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, or array of objects, to be used to create a new schema instances, whose properties conform to the resource type's schema
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);
}
}
}
ResourceDescription
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
|