@fdot/arculus-staff-service
    TypeScript icon, indicating that this package has built-in type declarations

    3.2.0 • Public • Published

    FDOT Arculus Staff Service

    NPM package to assist accessing FDOT Staff information through the Arculus Staff Service v3 API in both test and production.

    Benefits of Using this Package

    Full Typescript Support

    This package was created in TypeScript and thus has full type support.

    Caching

    Caching is not enabled by default but can be enabled via the options during initialization. When caching is enabled, a cache duration setting controls when cached entries will be purged from the cache. A sliding cache option can also be used to slide the expiration forward every time that cached element is accessed. All exposed functions in this package use caching if caching is enabled. The caching options provided during initialization can be overridden via a cache option parameter available on each exposed function.

    Automatic Throttle Retry

    The Arculus Staff Service is hosted on Azure API Management and can return a HTTP Status Code: 429 when throttle thresholds are met. When this happens a retry-after header will be returned along with the 429 with the number of seconds that should elapse before another attempt to call the api operation. This package will automatically wait the specified time and then issue another attempt.

    Automatic Support for Custom Mapping

    If you wish to transform the IStaffMember returned from functions in this package every available function has a corollary method that takes your custom map function and will perform all mapping before returning staff data.

    Runtime Engine Agnostic

    This package has no browser specific or Node.js specific dependencies so you can use it on the server side and client side of your application.

    Getting Started

    Install the package

    npm install @fdot/arculus-staff-service

    Import necessary types and methods:

    import {
        Environment,
        IStaffMember,
        IStaffServiceOptions,
        ICacheOptions,
        staffService,
    } from "@fdot/arculus-staff-service";

    Create a IStaffServiceOptions object with the necessary information:

    const cacheOptions: ICacheOptions = {
        cacheDurationInMinutes: 60,
        cachingEnabled: true,
        slidingExpirationEnabled: true
    };
    
    const options: IStaffServiceOptions = {
        arculusApiKey: "InsertYourKeyHere",
        cacheOptions,
        environment: Environment.Test
    };

    JavaScript example for those less privileged: 😁

    const cacheOptions = {
        cacheDurationInMinutes: 60,
        cachingEnabled: true,
        slidingExpirationEnabled: true
    }; 
    
    const testOptions = {
        arculusApiKey: "InsertYourKeyHere",
        cacheOptions,
        environment: "Test"
    };
    
    const productionOptions = {
        arculusApiKey: "InsertYourKeyHere",
        cacheOptions,
        environment: "Production"
    };

    Initialize the service:

    staffService.initialize(options);

    Use the service:

    const staffMember : IStaffMember = await staffService.getStaffByEmailAddress("cody.raffensperger@dot.state.fl.us");

    JavaScript example for those less privileged: 😁

    const staffMember = await staffService.getStaffByEmailAddress("cody.raffensperger@dot.state.fl.us");

    Use the service with a custom map function if you only care about a subset of properties or wish to transform anything:

    interface IStaff = {
        srsId: number;
        email: string;
    }
    
    const mapFunction = (staff: IStaffMember) : IStaff => {
        return {
            srsId: staff.id,
            email: staff.emailAddress
        };
    }
    
    const staff : IStaff = await staffService.getMappedStaffByEmailAddress<IStaff>(
        "cody.raffensperger@dot.state.fl.us",
        mapFunction);

    JavaScript example for those less privileged: 😁

    const mapFunction = (staff) => {
        return {
            srsId: staff.id,
            email: staff.emailAddress
        };
    }
    
    const staff = await staffService.getMappedStaffByEmailAddress(
        "cody.raffensperger@dot.state.fl.us",
        mapFunction);

    Prerequisites

    A subscription key with access to call the FDOT Arculus Staff Service API in the environment specified is required to use this package. To request a key for the Test environment visit the FDOT Arculus Azure API Management Developer Portal. The Arculus API Product Group is the product you will want to request a subscription to gain access to FDOT staff information.

    Available Staff Service Methods

    export declare const initialize: (options: IStaffServiceOptions) => void;
    
    export declare const getStaffByAzureOid: (oid: string, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember | null>;
    export declare const getMappedStaffByAzureOid: <T>(oid: string, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T | null>;
    
    export declare const getStaffByAzureOids: (oids: string[], cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember[]>;
    export declare const getMappedStaffByAzureOids: <T>(oids: string[], mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T[]>;
    
    export declare const getStaffByEmailAddress: (emailAddress: string, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember | null>;
    export declare const getMappedStaffByEmailAddress: <T>(emailAddress: string, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T | null>;
    
    export declare const getStaffBySrsId: (srsId: number, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember | null>;
    export declare const getMappedStaffBySrsId: <T>(srsId: number, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T | null>;
    
    export declare const getStaffBySrsIds: (srsIds: number[], cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember[]>;
    export declare const getMappedStaffBySrsIds: <T>(srsIds: number[], mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T[]>;
    
    export declare const getActiveStaffByPartialName: (partialName: string, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember[]>;
    export declare const getMappedActiveStaffByPartialName: <T>(partialName: string, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T[]>;
    
    export declare const getActiveAndInactiveStaffByPartialName: (partialName: string, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember[]>;
    export declare const getMappedActiveAndInactiveStaffByPartialName: <T>(partialName: string, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T[]>;
    
    export declare const getStaffByFilterCriteria: (filterCriteria: IStaffFilterCriteria, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember[]>;
    export declare const getMappedStaffByFilterCriteria: <T>(filterCriteria: IStaffFilterCriteria, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T[]>;
    
    export declare const getAllStaffMembers: (cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember[]>;
    export declare const getAllMappedStaffMembers: <T>(mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T[]>;
    
    export declare const getDirectReports: (srsId: number, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember[]>;
    export declare const getMappedDirectReports: <T>(srsId: number, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T[]>;
    
    export declare const getManager: (srsId: number, cacheOptions?: ICacheOptions | undefined) => Promise<IStaffMember>;
    export declare const getMappedManager: <T>(srsId: number, mapFunction: (staff: IStaffMember) => T, cacheOptions?: ICacheOptions | undefined) => Promise<T>;
    
    export declare const clearCache: () => void;

    Tests

    The tests for this package were developed using Jest with the help of the TypeScript pre processor ts-jest.

    The tests require a key to the arculus API for the test environment. Create an .env file in the root of this package with the following:

    ARCULUS_API_KEY=[Enter Your Key Here]

    Once the .env file is in place the tests can be executed by simply running the following command:

    npm run test

    To debug the tests set your breakpoints in VSCode and then launch the 'Jest All' debug configuration.

    After executing the Jest tests a code coverage reports can be found at: .\coverage\lcov-report\index.html.

    Contributing

    Any user with the appropriate rights within FDOT Azure Dev Ops can contribute to this package.

    Authors

    • Cody Raffensperger - Initial work - NPM Page

    License

    This project is licensed under the MIT License.

    Install

    npm i @fdot/arculus-staff-service

    DownloadsWeekly Downloads

    68

    Version

    3.2.0

    License

    ISC

    Unpacked Size

    78.9 kB

    Total Files

    50

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar