@skedip/ukg-dimensions

UKG Dimensions API connector package for SkedIP integrations. This package provides a TypeScript-based client library for interacting with UKG Dimensions APIs, including timekeeping, scheduling, and people management.

Table of Contents

• Features
• Prerequisites
• Installation
• Setup
• Development
• Debugging
• Testing
• Building
• Publishing to NPM
• Usage
• API Reference
• Contributing

Features

• Client Management: Centralized HTTP client with automatic authentication
• People Management: Retrieve and manage person data, employee references, and extensions
• Scheduling: Access employee schedule patterns and availability data
• Timekeeping: Retrieve and update timecard information
• Commons: Utilities for hyperfinds, pay periods, and symbolic periods
• Type-Safe: Full TypeScript support with comprehensive type definitions

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: v18.x or higher
• npm: v9.x or higher (comes with Node.js)
• Git: For version control
• TypeScript: v5.x (installed as dev dependency)

Installation

For consumers of this package:

npm install @skedip/ukg-dimensions

For development:

# Clone the repository (if not already done)
cd /path/to/SkedIP/connectors/ukg-dimensions

# Install dependencies
npm install

Setup

1. Configuration

This package requires UKG Dimensions configuration to be passed via a skedContext parameter. The configuration should include:

{
  "UKG_DIMENSIONS_USER_NAME": "your-username",
  "UKG_DIMENSIONS_CLIENT_ID": "your-client-id",
  "UKG_DIMENSIONS_CLIENT_SECRET": "your-client-secret",
  "UKG_DIMENSIONS_PASSWORD": "your-password",
  "UKG_DIMENSIONS_APP_KEY": "your-app-key",
  "UKG_DIMENSIONS_HOST_NAME": "https://your-ukg-instance.com"
}

The skedContext can be a JSON string containing these variables under various paths:

• configuration.variables
• variables
• env
• Or directly at the root level

2. Development Environment Setup

For local testing and development, create a .env file (not tracked in git):

# Copy the example environment file
cp /path/to/mainFn/.env.example .env.local

# Edit the file with your credentials
# Note: Keep your credentials secure and never commit them

Example .env.local structure:

UKG_DIMENSIONS_USER_NAME=your-username
UKG_DIMENSIONS_PASSWORD=your-password
UKG_DIMENSIONS_HOST_NAME=https://your-ukg-instance.com
UKG_DIMENSIONS_CLIENT_ID=your-client-id
UKG_DIMENSIONS_CLIENT_SECRET=your-client-secret
UKG_DIMENSIONS_APP_KEY=your-app-key

3. Verify Installation

# Build the project
npm run build

# Run tests
npm test

Development

Project Structure

src/
├── client/           # HTTP client and authentication
├── commons/          # Shared utilities (hyperfinds, pay periods, etc.)
├── models/           # TypeScript type definitions
├── people/           # People management APIs
├── scheduling/       # Scheduling and availability APIs
├── timekeeping/      # Timecard management APIs
└── utils/            # Helper utilities and constants

tests/
├── integration/      # Integration tests (require UKG credentials)
└── unit/            # Unit tests (mocked)

Development Workflow

1. Make changes to source files in src/
2. Run tests to verify your changes
3. Build the project to compile TypeScript
4. Format code using Prettier

# Build and watch for changes
npm run build

# Format code
npm run prettier-format

# Run tests with coverage
npm test

Code Style

This project uses:

• ESLint for linting
• Prettier for code formatting
• TypeScript strict mode

Configuration files:

• .eslintrc.json - ESLint rules
• .prettierrc - Prettier formatting rules
• tsconfig.json - TypeScript compiler options

Debugging

VS Code Debugging

This project includes VS Code launch configurations for debugging:

1. Debug Current TypeScript File

1. Open any .ts file in src/
2. Press F5 or select "Debug Current TS File (ts-node)" from the debug menu
3. The file will be executed with ts-node and debugger attached

2. Debug Jest Unit Tests

1. Open a test file (e.g., tests/unit/client/client.spec.ts)
2. Set breakpoints by clicking in the gutter
3. Select "Jest Current File" from the debug menu
4. Press F5 to start debugging

3. Debug Specific Test

1. Open a test file
2. Highlight the test name (text within it('test name', ...)
3. Select "Jest Current Selected Test" from the debug menu
4. Press F5 to debug only that test

4. Debug Jest in Terminal

For debugging tests with Node.js inspector:

npm run jest:debug

Then:

1. Open Chrome and navigate to chrome://inspect
2. Click "Open dedicated DevTools for Node"
3. Set breakpoints and debug

Integration Testing

Integration tests require valid UKG Dimensions credentials. To run them:

1. Configure your skedContext with valid credentials
2. Update the test file to enable the test (uncomment function calls)
3. Run specific integration test:

// Example: tests/integration/people/person-it.ts
// Uncomment the function you want to test
retrieveEmployeeReferences()

4. Execute with ts-node:

npx ts-node tests/integration/people/person-it.ts

Debugging Tips

• Check logs: All API calls are made through AxiosClient from @skedip/utils
• Inspect network: Add breakpoints in src/client/client.ts to inspect requests/responses
• Authentication issues: Debug src/client/access-token.ts for token retrieval
• Configuration errors: Check src/commons/configuration-service.ts for context parsing

Testing

Run All Tests

# Run all tests with coverage
npm test

# Run tests in watch mode
npx jest --watch

# Run tests with verbose output
npx jest --verbose

Run Specific Tests

# Run unit tests only
npx jest tests/unit

# Run integration tests only
npx jest tests/integration

# Run specific test file
npx jest tests/unit/client/client.spec.ts

# Run tests matching pattern
npx jest --testNamePattern="should retrieve persons"

Test Coverage

Coverage reports are generated in:

• coverage/ directory (HTML report)
• Console output (summary)

Thresholds and configuration are defined in jest.config.ts.

Writing Tests

Follow the existing patterns:

Unit tests (in tests/unit/):

• Mock external dependencies
• Test individual functions and classes
• Fast execution

Integration tests (in tests/integration/):

• Test against real UKG API (or test environment)
• Require valid credentials
• Commented out by default

Building

Build for Distribution

# Clean build
rm -rf dist/
npm run build

This compiles TypeScript to JavaScript in the dist/ directory with:

• Compiled .js files
• Type definition .d.ts files
• Source maps .js.map files

Build Output

dist/
├── index.js
├── index.d.ts
├── client/
├── commons/
├── models/
├── people/
├── scheduling/
├── timekeeping/
└── utils/

Verify Build

# Check the output
ls -la dist/

# Test the built package locally
npm pack
# This creates a .tgz file that can be installed locally for testing

Publishing to NPM

Prerequisites for Publishing

1. NPM Account: Create an account at npmjs.com
2. Organization Access: Ensure you have publish rights to @skedip scope
3. Authentication: Login to NPM

npm login
# Enter your npm credentials

Pre-publish Checklist

Before publishing, ensure:

• [ ] All tests pass: npm test
• [ ] Code is formatted: npm run prettier-format
• [ ] Build succeeds: npm run build
• [ ] Version is updated in package.json
• [ ] CHANGELOG is updated (if applicable)
• [ ] No sensitive data in code or config files
• [ ] files field in package.json includes only necessary files

Version Management

Follow Semantic Versioning:

• MAJOR version for incompatible API changes
• MINOR version for backwards-compatible functionality
• PATCH version for backwards-compatible bug fixes

Update version:

# Patch release (1.0.1 -> 1.0.2)
npm version patch

# Minor release (1.0.1 -> 1.1.0)
npm version minor

# Major release (1.0.1 -> 2.0.0)
npm version major

This automatically:

• Updates package.json
• Creates a git commit
• Creates a git tag

Publishing Steps

1. Prepare the Release

# Ensure you're on the main/master branch
git checkout main
git pull origin main

# Ensure clean working directory
git status

# Run full test suite
npm test

# Build the package
npm run build

2. Update Version

# For example, patch version
npm version patch -m "Release v%s"

# This creates a commit and tag

3. Publish to NPM

# Dry run to see what would be published
npm publish --dry-run

# Publish to NPM (public scope)
npm publish --access public

4. Push to Git Repository

# Push commits and tags
git push origin main
git push origin --tags

Publishing to a Specific Tag

For pre-release versions:

# Update to pre-release version
npm version 1.1.0-beta.1

# Publish with beta tag
npm publish --tag beta --access public

# Users can install with:
# npm install @skedip/ukg-dimensions@beta

Verify Publication

1. Check on NPM: https://www.npmjs.com/package/@skedip/ukg-dimensions
2. Test installation in a separate project:

mkdir test-install && cd test-install
npm init -y
npm install @skedip/ukg-dimensions
node -e "const ukgClient = require('@skedip/ukg-dimensions'); console.log(ukgClient);"

Unpublishing (Emergency Only)

⚠️ Warning: Unpublishing is discouraged and has restrictions.

# Unpublish a specific version (within 72 hours)
npm unpublish @skedip/[email protected]

# Deprecate instead (preferred)
npm deprecate @skedip/[email protected] "Critical bug, please upgrade to 1.0.2"

CI/CD Publishing (Recommended)

For automated publishing via GitHub Actions or similar:

1. Add NPM token as a secret
2. Create a workflow file:

name: Publish to NPM

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Usage

Basic Example

import { Client, Person, Timecards } from '@skedip/ukg-dimensions';

// Create configuration context
const skedContext = JSON.stringify({
  configuration: {
    variables: {
      UKG_DIMENSIONS_USER_NAME: 'your-username',
      UKG_DIMENSIONS_CLIENT_ID: 'your-client-id',
      UKG_DIMENSIONS_CLIENT_SECRET: 'your-client-secret',
      UKG_DIMENSIONS_PASSWORD: 'your-password',
      UKG_DIMENSIONS_APP_KEY: 'your-app-key',
      UKG_DIMENSIONS_HOST_NAME: 'https://your-ukg-instance.com'
    }
  }
});

// Use the client
async function example() {
  // Retrieve persons
  const persons = await Person.retrieveAllPersons({
    where: {
      employmentStatus: 'Active'
    },
    index: 0,
    count: 100
  }, skedContext);

  console.log('Retrieved persons:', persons);

  // Retrieve timecards
  const timecards = await Timecards.retrieveTimecards({
    /* request body */
  }, skedContext);

  console.log('Timecards:', timecards);
}

Using the HTTP Client Directly

import { Client } from '@skedip/ukg-dimensions';

const skedContext = '{ "UKG_DIMENSIONS_HOST_NAME": "...", ... }';

// Build and execute request
const response = await Client.Builder
  .build(skedContext)
  .url('v1/commons/persons')
  .headers({ 'Content-Type': 'application/json' })
  .data({ /* request body */ })
  .post();

console.log('Response:', response);

API Reference

Main Exports

• Client: HTTP client builder for custom requests
• Person: People management APIs
• Timecards: Timekeeping operations
• Commons: Hyperfinds, pay periods, symbolic periods
• Models: TypeScript type definitions

Documentation

For detailed API documentation, refer to:

• Source code in src/ directory
• Type definitions in dist/*.d.ts after building
• Integration test examples in tests/integration/

Contributing

Development Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Code Quality

All contributions must:

• Pass all existing tests
• Include new tests for new functionality
• Follow existing code style (enforced by ESLint/Prettier)
• Include TypeScript type definitions
• Update documentation as needed

License

ISC

Support

For issues and questions:

• Issues: https://github.com/Skedulo/SkedIP/issues
• Organization: Skedulo - Integration Team

Package Information:

• Name: @skedip/ukg-dimensions
• Version: 1.0.1
• Repository: https://github.com/Skedulo/SkedIP
• NPM: https://www.npmjs.com/package/@skedip/ukg-dimensions