Class: SCIMMY.Types.Resource

SCIM Resource Type

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
Name Type Description
filteropt String

the filter to be applied on ingress/egress by implementing resource

excludedAttributesopt String

the comma-separated string list of attributes or filters to exclude on egress

attributesopt String

the comma-separated string list of attributes or filters to include on egress

sortByopt String

the attribute retrieved resources should be sorted by

sortOrderopt String

the direction retrieved resources should be sorted in

startIndexopt Number

offset index that retrieved resources should start from

countopt Number

maximum number of retrieved resources that should be returned in one operation

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
Name Type Description
sortByopt String

the attribute retrieved resources should be sorted by

sortOrderopt String

the direction retrieved resources should be sorted in

startIndexopt Number

offset index that retrieved resources should start from

countopt Number

maximum number of retrieved resources that should be returned in one operation

Members

(abstract, static) endpoint: String

Retrieves a resource's endpoint relative to the service provider's base URL

Type:
{String}

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

Type:
{SCIMMY.Types.Resource|String}

(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

Type:
{Object}
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
Name Type Description
schema String

URN namespace of the schema extension that augments the resource

required Boolean

whether resource instances must include the schema extension