FDOT Arculus Staff Service

NPM package to assist accessing FDOT Staff information through the Arculus Staff Service v4 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 accepts a custom map function and will perform that 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(
  "[email protected]"
);

JavaScript example for those less privileged: 😁

const staffMember = await staffService.getStaffByEmailAddress(
  "[email protected]"
);

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>(
    "[email protected]",
    mapFunction);

JavaScript example for those less privileged: 😁

const mapFunction = (staff) => {
  return {
    srsId: staff.id,
    email: staff.emailAddress,
  };
};

const staff = await staffService.getMappedStaffByEmailAddress(
  "[email protected]",
  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: (
  statusFilter: StatusFilter = StatusFilter.ActiveOnly,
  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.