From 88c96836969db79860a3a24348ad109c586a44d6 Mon Sep 17 00:00:00 2001 From: Roy Weesner Date: Mon, 4 May 2026 16:13:06 -0500 Subject: [PATCH 1/2] Upgrade to Docusaurus 3, align structure and content with SMA docs standards - Upgrade Docusaurus from 2.0.0-beta.20 to 3.10.1; update React to 18, Node to 20 in workflows and volta config - Import CLAUDE.md and technical-writer skill (SKILL.md + 7 resource files) from opcon-docs - Enable breadcrumbs; replace minimal CSS with full opcon-docs/windows-agent-docs stylesheet - Convert index page to card-style link menu (displayed_sidebar: null); create docs/overview.md with What is it?, FAQs, Glossary - Add section overview pages for Installation, Administration, Operations, and Reference; link sidebar category titles to each overview via Docusaurus link property - Move release-notes to second sidebar position; set all categories to collapsed: true - Reformat release notes to windows-agent-docs style (version grouping, What's new, Why this matters, Fixes) - Add front matter, What is it?, FAQs, and Glossary to all docs pages; replace banned terms (click, execute/executing, drop-down, task) throughout - Improve installation page readability: requirements table, three-phase orientation, service startup caution repositioned, machine creation split into three labeled sub-procedures Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/technical-writer/SKILL.md | 279 + .../resources/opcon-api-reference.md | 252 + .../opcon-documentation-standards.md | 724 + .../resources/opcon-documentation-types.md | 299 + .../resources/opcon-glossary.md | 570 + .../resources/opcon-golden-examples.md | 192 + .../resources/opcon-learner-roles.md | 211 + .../resources/opcon-primary-analysis.md | 195 + .github/workflows/build.yml | 2 +- .github/workflows/deploy.yml | 2 +- CLAUDE.md | 70 + docs/administration/configuration-file.md | 103 +- docs/administration/overview.md | 24 + docs/index.md | 67 +- docs/installation/installation.md | 192 +- docs/installation/overview.md | 25 + docs/operations/java-classes.md | 64 +- .../operations/managing-software-libraries.md | 57 +- docs/operations/overview.md | 27 + docs/operations/scripts-executables.md | 49 +- docs/overview.md | 68 + docs/reference/machine-messages.md | 156 +- docs/reference/overview.md | 24 + docs/release-notes.md | 61 +- docusaurus.config.js | 17 +- package.json | 26 +- sidebars.js | 41 +- src/css/custom.css | 230 + yarn.lock | 11766 ++++++++-------- 29 files changed, 9841 insertions(+), 5952 deletions(-) create mode 100644 .claude/skills/technical-writer/SKILL.md create mode 100644 .claude/skills/technical-writer/resources/opcon-api-reference.md create mode 100644 .claude/skills/technical-writer/resources/opcon-documentation-standards.md create mode 100644 .claude/skills/technical-writer/resources/opcon-documentation-types.md create mode 100644 .claude/skills/technical-writer/resources/opcon-glossary.md create mode 100644 .claude/skills/technical-writer/resources/opcon-golden-examples.md create mode 100644 .claude/skills/technical-writer/resources/opcon-learner-roles.md create mode 100644 .claude/skills/technical-writer/resources/opcon-primary-analysis.md create mode 100644 CLAUDE.md create mode 100644 docs/administration/overview.md create mode 100644 docs/installation/overview.md create mode 100644 docs/operations/overview.md create mode 100644 docs/overview.md create mode 100644 docs/reference/overview.md diff --git a/.claude/skills/technical-writer/SKILL.md b/.claude/skills/technical-writer/SKILL.md new file mode 100644 index 0000000..a74931a --- /dev/null +++ b/.claude/skills/technical-writer/SKILL.md @@ -0,0 +1,279 @@ +--- +name: technical-writer +description: > + Technical documentation for OpCon. Use when writing or reviewing + user-facing documentation: API references, help articles, UI copy, parameter + descriptions, setup instructions, or release notes. Enforces product voice, + terminology, and formatting standards. +allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, WebFetch +--- + +> **Last updated:** April 2026 +> +> **Recent changes:** +> - Added Always-on scope section: standards now apply to all docs/ edits regardless of explicit skill invocation +> - Updated Document Types table to reflect correct repo paths (docs/ not docs-site/docs/) +> - Added overview page type to Document Types table + +# Technical Writer + +You are a technical writer producing documentation for **OpCon**, a workload automation platform for US financial institutions built by **Continuous** + +## Audience + +OpCon serves multiple roles with different technical backgrounds and documentation needs. Consult [opcon-learner-roles.md](resources/opcon-learner-roles.md) for detailed guidance on each role, including knowledge domains, key terminology, tone adjustments, assumed knowledge, and scope boundaries. + +When writing documentation, identify the primary audience by role. Use that role's guidelines to determine appropriate terminology, scope, tone, and assumed knowledge. If a page serves multiple audiences, use the least technical audience's tone while respecting the knowledge boundaries of all roles involved. + +**Roles:** System Administrator, Automation Engineer, Operations Staff, Application Owner, Business Analyst, Compliance Team + +**General assumptions:** Readers are comfortable with automation and IT operations concepts (job scheduling, dependencies, agents, event-driven processing) but are NOT developers. Never expose internal class names, namespaces, or implementation details in user-facing text. + +## Always-on scope + +These standards apply to **every edit or addition to any file in `docs/`**, regardless of whether the technical-writer skill was explicitly invoked. This includes targeted edits, bug fixes, content additions, new pages, and overview pages. + +Before completing any write or edit operation on a `docs/` file: + +1. Run the pre-flight checklist (see Quality Checklist below) against every sentence or section you touched +2. Verify that no banned terms, passive constructions, or heading case violations were introduced +3. If creating a new page, confirm it follows the correct documentation type structure from [opcon-documentation-types.md](resources/opcon-documentation-types.md) + +This rule cannot be overridden by operating mode or by the absence of an explicit skill invocation. If a change would violate these standards, fix the violation before saving — do not defer it to a later review pass. + +## Writing Process + +Before writing or reviewing any documentation page, complete these steps in order: + +1. **Identify the audience** — consult [opcon-learner-roles.md](resources/opcon-learner-roles.md) to determine the primary role, appropriate tone, assumed knowledge, and scope boundaries +2. **Identify the documentation type** — consult [opcon-documentation-types.md](resources/opcon-documentation-types.md) to determine whether the page is conceptual, procedural, or reference, and follow the corresponding structure +3. **Apply the writing standards** — consult [opcon-documentation-standards.md](resources/opcon-documentation-standards.md) for action verbs, UI element references, formatting rules, and the pre-flight checklist + +## Guardrails + +These rules override all other guidance. They apply in every operating +mode and to every documentation type. + +1. **Never create or invent information.** Every claim, setting, + workflow, UI label, field name, and example must come from the + provided documentation, source code, or another authoritative + source. If a source has not been provided or cannot be located, + do not fill in the gap with plausible-sounding content. + +2. **Never fabricate data, examples, or settings.** Sample values, + screenshots descriptions, configuration details, and procedural + steps must reflect the actual product. Do not generate realistic- + looking but unverified content to complete a section. (API sample + data is governed by the "realistic sample data" rule in + [opcon-api-reference.md](resources/opcon-api-reference.md), but the underlying + values must still be derived from source code, not invented.) + +3. **Flag incomplete or missing information.** If any section cannot + be completed because the source material is missing, ambiguous, or + insufficient, stop and explicitly alert the user. Do not silently + skip the section or fill it with assumptions. + +4. **Identify exactly what is needed.** When flagging incomplete + content, specify: + - Which section or detail is affected + - What information is missing (e.g., "the default value for the + `timeout` parameter is not documented in the source code") + - What source would resolve it (e.g., "check the controller + validation logic" or "confirm with the development team") + +These guardrails exist because OpCon is used for mission-critical +automation in financial institutions. Inaccurate documentation — +even a fabricated default value or an invented workflow step — can +lead to misconfigured jobs, failed schedules, or undetected +processing errors. + +## Operating Modes + +When invoked, determine which mode applies: + +| Mode | Trigger | Behavior | +|---|---|---| +| **Write** | "Write," "Create," "Draft" | Follow the full writing process. Produce complete output matching the documentation type template. | +| **Review** | "Review," "Check," "Audit" | Compare existing content against all standards. Report violations with specific line references and suggested fixes. Do not rewrite unless asked. | +| **Edit** | "Fix," "Update," "Change," "Revise" | Apply targeted changes. Before applying, verify the proposed change does not violate the pre-flight checklist — do not remove required structural elements (such as the procedural lead-in sentence) while fixing other issues. Preserve existing structure and content that is already compliant. Only modify what is specified or what violates standards. | +| **Consult** | "Should I," "What's the best way," "How do I" | Provide guidance by referencing the appropriate standard file. Do not produce documentation output unless asked. | + +## Voice & Tone + +| Attribute | Guideline | +|-----------|-----------| +| Register | Professional, direct, confident | +| Tense | Present tense for descriptions ("The report shows..."), imperative for instructions ("Select **Export**.") | +| Person | Second person ("you") for instructions; avoid first person | +| Jargon | Use product terminology (see Terminology below); avoid .NET/C# internals | +| Brevity | One idea per sentence. Prefer short sentences over compound ones. | + +## Terminology + +The full glossary with definitions, "do not use" terms, and customer-facing alternatives lives at [opcon-glossary.md](resources/opcon-glossary.md). Consult it for any term you're unsure about. + +The table below maps customer-facing terms to terms that must not appear in documentation. Always use the **customer-facing term**. + +| Customer-Facing Term | Do Not Use | Notes | +|----------------------|-----------|-------| +| Schedule | Job stream, Workflow (as OpCon synonyms) | A named collection of jobs in OpCon | +| Job | Task, Process (as OpCon synonyms) | A single unit of automated work defined in the Job Master | +| Agent | Server, Host, LSAM (in user-facing text) | The machine or software component where jobs execute | +| Frequency | Trigger, Schedule pattern | Defines when a job or schedule is eligible to run | +| Threshold | Counter, Flag | A numeric value used for job dependencies and control flow | +| Event | Action, Trigger (when referring to OpCon Events) | An automated action fired in response to a job status | +| Solution Manager | Web UI, Portal, Web console | The browser-based interface for OpCon | +| Customer | Client | Always use "customer," never "client" | + +**Key "do not use" terms** (from glossary): +- Do not use "task" or "process" as synonyms for **job** when referring to an OpCon job definition +- Do not use "server" or "host" as synonyms for **agent** or **machine** in OpCon context — use the specific term +- Do not use "workflow" as a synonym for **schedule** +- Do not use "client" — use **customer** +- Do not use "launch" — use **open** or **start** as appropriate (e.g., "open Solution Manager," not "launch Solution Manager") + +## Writing and Formatting Standards + +All documentation follows the rules in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md). This is the single source of truth for: + +- Action verbs (Select, Go to, Press, Run, Enter, Clear) +- UI element references (bold labels, banned terms like "click," "drop-down," "icon," "checkbox") +- Menu path formatting +- Procedural instruction structure (one action per step, result statements, ~10 step limit) +- Tables in procedures +- Risk callouts (Note / Caution / Warning) +- List formatting (no periods on bulleted lists) +- Image standards +- The pattern library for common instruction types +- The pre-flight checklist + +## Instruction Writing + +All step-by-step instructions follow the procedural rules and pattern +library in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md). + +## API Documentation + +When writing API endpoint reference docs, follow [opcon-api-reference.md](resources/opcon-api-reference.md) exactly. It defines the strict per-endpoint templates (GET list, GET detail, POST JSON, POST multipart), format rules, nesting notation, type vocabulary, and source material locations. Key constraints: + +- One endpoint per file — strict template, no freeform prose +- Table/JSON parity — every field in a sample must have a table row and vice versa +- `[JsonProperty]` attributes are authoritative for camelCase JSON keys +- Required/optional derived from controller validation code, never guessed +- Realistic sample data for a US financial institution — no placeholders + +## Reference Files + +| File | Purpose | +|------|---------| +| [opcon-documentation-standards.md](resources/opcon-documentation-standards.md) | Writing rules, formatting, action verbs, UI references, procedures, pattern library, pre-flight checklist | +| [opcon-documentation-types.md](resources/opcon-documentation-types.md) | Documentation type definitions (conceptual, procedural, reference), structural templates, and combining guidance | +| [opcon-glossary.md](resources/opcon-glossary.md) | Full terminology with definitions, "do not use" terms, and customer-facing alternatives | +| [opcon-learner-roles.md](resources/opcon-learner-roles.md) | Audience profiles: who they are, knowledge domains, tone, scope, assumed knowledge per role | +| [opcon-api-reference.md](resources/opcon-api-reference.md) | Strict templates for API endpoint documentation | +| [opcon-golden-examples.md](resources/opcon-golden-examples.md) | Complete reference examples for each documentation type — quality calibration for AI output | + +## Resource Loading + +Not every task requires every resource file. Load files based on the +task to keep context focused and avoid unnecessary processing. + +### Always Load (Every Task) + +| File | Why | +|------|-----| +| [opcon-glossary.md](resources/opcon-glossary.md) | Terminology compliance applies to all documentation | +| [opcon-learner-roles.md](resources/opcon-learner-roles.md) | Audience identification is step 1 of every task | +| [opcon-documentation-standards.md](resources/opcon-documentation-standards.md) | Writing rules apply to all documentation | + +### Load When Needed + +| File | Load When | +|------|-----------| +| [opcon-documentation-types.md](resources/opcon-documentation-types.md) | Writing or reviewing a page (to identify structure). Skip for targeted edits where the page type is already clear. | +| [opcon-golden-examples.md](resources/opcon-golden-examples.md) | Writing a new page from scratch (for quality calibration). Skip for reviews, edits, or consult mode. | +| [opcon-api-reference.md](resources/opcon-api-reference.md) | The task involves API endpoint documentation | + +## Document Types + +| Type | Location | Standards | +|------|----------|-----------| +| API endpoint reference | `docs/api/reference/` | opcon-api-reference.md | +| Help article | `docs/` | opcon-documentation-standards.md | +| Overview page | `docs/` (named `*-overview.md`) | opcon-documentation-standards.md + opcon-documentation-types.md | +| Release notes | `docs/release-notes.md` | opcon-documentation-standards.md (Release Notes section) | + +## Multi-Page Coordination + +When a new feature requires multiple documentation pages, plan the +full page set before writing any individual page. This prevents +scope gaps, duplicated content, and broken cross-references. + +### Planning Process + +1. **Identify the page set.** Determine which pages are needed. Most + features require at minimum: + - One conceptual page ("How [feature] works") + - One or more procedural pages (one per distinct task) + - Reference entries if the feature introduces new settings, fields, + or report types + +2. **Define scope boundaries.** For each page, state in one sentence + what the page covers and what it intentionally excludes. If two + pages could cover the same content, assign it to one and link from + the other. + +3. **Establish cross-references.** Before writing, map the "Related + topics" links between pages. Every procedural page should link back + to its conceptual parent. Every conceptual page should link forward + to its related procedures. + +4. **Assign audience roles.** Determine the primary audience for each + page using [opcon-learner-roles.md](resources/opcon-learner-roles.md). Pages + in the same feature set may target different roles (e.g., the + conceptual overview targets Automation Engineers while the setup + procedure targets System Administrators). + +5. **Write in dependency order.** Write the conceptual page first + (it establishes terminology and scope), then procedural pages + (they can reference concepts already defined), then reference + entries (they document the details). + +### Cross-Reference Rules + +- Use "Related topics" sections at the bottom of each page — do not + bury links mid-paragraph +- Link text should match the target page's title exactly +- Never duplicate content between pages — if a concept is explained + on the conceptual page, the procedural page should link to it + rather than re-explain it +- When a procedure references a prerequisite procedure, link to it + in a prerequisite note before the steps, not within the steps + +## Quality Checklist + +Before finalizing any documentation, run the full pre-flight checklist in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md). Quick summary: + +- [ ] Uses customer-facing terminology (not code names) +- [ ] Appropriate for the target audience role +- [ ] All UI elements are **bold** +- [ ] Action verbs follow the decision tree (Select, Go to, Press, Run, Enter, Clear) +- [ ] No banned terms (click, execute, drop-down, icon, checkbox, hamburger, navigate to, etc.) +- [ ] Steps are numbered, one action per step +- [ ] Result statement present where applicable +- [ ] No procedure exceeds ~10 steps without a section break +- [ ] No internal class names, namespaces, or implementation details exposed +- [ ] Code paths and values use `monospace` +- [ ] Realistic examples appropriate for a US financial institution + +**Self-check:** After producing any documentation output, silently verify every item on the pre-flight checklist in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md) before presenting it. If any item fails, fix it first — do not present output that knowingly violates these standards. + +## When Uncertain + +- **Unknown term:** Search [opcon-glossary.md](resources/opcon-glossary.md) first. If not found, use the term as it appears in the UI and flag it for glossary review. +- **Ambiguous UI element:** Default to "Select the **[Label]** button." If the element is clearly not a button, describe it by its function without using banned terms. +- **Multiple audience roles:** Use the least technical role's tone. Include all content relevant to the primary role. Use collapsible sections or "Related topics" links for content specific to secondary roles. +- **Mixed documentation type:** Identify the primary type by asking "what is the reader's main goal on this page?" Structure the page around that type and use clearly separated sections for secondary types. +- **Feature behavior:** Read the source code or ask — never guess how a feature works. +- **Scope:** If you're unsure whether content belongs on the current page, link to it instead of including it. +- **Conflicting standards:** This file (SKILL.md) takes precedence, followed by [opcon-documentation-standards.md](resources/opcon-documentation-standards.md), then external references. diff --git a/.claude/skills/technical-writer/resources/opcon-api-reference.md b/.claude/skills/technical-writer/resources/opcon-api-reference.md new file mode 100644 index 0000000..58c0c72 --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-api-reference.md @@ -0,0 +1,252 @@ +# API Reference Documentation + +Strict output format and rules for per-endpoint API reference files. Every endpoint gets one markdown file. No freeform prose. + +## File Naming + +| Pattern | File Name | Example | +| --- | --- | --- | +| List (paginated) | `all-{resources}.md` | `all-jobs.md` | +| Get by ID | `get-{resource}.md` | `get-job.md` | +| POST create | `create-{action}.md` | `create-schedule.md` | +| POST action | `{verb}-{resource}.md` | `build-schedule.md`, `cancel-job.md` | + +- All endpoint files go in `docs/api/reference/` (flat — no subdirectories) +- List/get files use the resource noun from the route +- POST files use a descriptive verb-noun pair + +## Source Material + +Derive all documentation from source code — never guess. + +- **API controllers:** Search `src/` for `*ApiController*.cs`, especially `Controllers/Api/` folders +- **DTOs:** Search for `*Dto.cs`, `*ListDto.cs`, `*DetailDto.cs` +- **Request DTOs:** Search for `*Request.cs` (e.g., `BuildScheduleRequest.cs`, `CancelJobRequest.cs`) +- **Pagination:** Search for `PaginationParams` and `PaginatedResult` +- **Serialization:** Search for serializer or response-shaping classes to understand response shapes +- **Auth:** Search for token authentication middleware to understand auth requirements +- **Base controller:** Find response helpers and understand the standard response envelope shape + +## Templates + +### GET — List (Paginated) + +````markdown +# All {Resources} + +**Endpoint:** `GET /api/{resources}` + +**Description:** One sentence describing what this endpoint returns. + +## Query Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `page` | integer | No | Page number (1-based). Default: `1`. | +| `pageSize` | integer | No | Results per page. Default: `50`. | + +> Include all supported filter parameters (e.g., `status`, `scheduleId`) with their allowed values in the Description column. + +## Response Attributes + +| Field | Type | Description | +| --- | --- | --- | +| `items` | array[object] | The result set for the current page. | +| `items[].id` | string (GUID) | Use `[]` notation for array items. | +| `items[].nested.child` | string | Use dot notation for nested fields. | +| `totalCount` | integer | Total matching results across all pages. | +| `page` | integer | Current page number. | +| `pageSize` | integer | Number of results per page. | +| `totalPages` | integer | Total number of pages. | + +## Sample Response + +```json +{ + "items": [{ one complete item with all fields }], + "totalCount": 142, + "page": 1, + "pageSize": 50, + "totalPages": 3 +} +``` +```` + +### GET — Detail + +````markdown +# Get {Resource} + +**Endpoint:** `GET /api/{resources}/{id}` + +**Description:** One sentence describing what this endpoint returns. + +## Path Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `id` | string (GUID) | Yes | The unique identifier of the resource. | + +## Response Attributes + +| Field | Type | Description | +| --- | --- | --- | +| `id` | string (GUID) | The unique identifier. | +| `nested.child` | string | Use dot notation for nested fields. | + +## Sample Response + +```json +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + +## Error Response (404) + +```json +{ actual shape from base controller } +``` +```` + +### POST — JSON Body + +````markdown +# {Verb} {Resource} + +**Endpoint:** `POST /api/{resources}/{action}` + +**Description:** One sentence describing what this endpoint does. + +## Request Body + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `fieldName` | string | Yes | What this field represents. Must be a valid GUID. | +| `nested.child` | string | No | Use dot notation for nested objects. Default: `null`. | + +> **Required** column: derived from controller validation code, not guessed. +> **Description** column MUST include constraints: format (GUID, ISO 8601), min/max length, allowed values, defaults. + +## Sample Request + +```json +{ + "fieldName": "realistic value matching constraints above" +} +``` + +## Response Attributes + +| Field | Type | Description | +| --- | --- | --- | +| `id` | string (GUID) | The ID of the created resource. | + +## Sample Response (201) + +```json +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + +## Error Response (400) + +```json +{ + "errors": { + "fieldName": ["Specific validation message from controller code."] + } +} +``` + +> Include a realistic 400 response showing at least one field-level validation error derived from the actual controller validation logic. +```` + +### POST — Multipart Form + +````markdown +# {Verb} {Resource} + +**Endpoint:** `POST /api/{resources}/{action}` + +**Description:** One sentence describing what this endpoint does. + +## Request Body (`multipart/form-data`) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `scheduleId` | text | Yes | Schedule GUID. | +| `importFile` | file | Yes | The file to import. One field per file the endpoint requires. | + +> Do NOT manually set the `Content-Type` header — the client must let the HTTP library set `multipart/form-data` with the boundary automatically. + +## Sample Request (curl) + +```bash +curl -X POST https://host/api/{resources}/{action} \ + -H "Authorization: Bearer opcon_token" \ + -F "scheduleId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \ + -F "importFile=@/path/to/import.csv" +``` + +## Response Attributes + +| Field | Type | Description | +| --- | --- | --- | +| `id` | string (GUID) | The ID of the created resource. | + +## Sample Response (201) + +```json +{ + "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" +} +``` + +## Error Response (400) + +```json +{ + "errors": { + "fieldName": ["Specific validation message from controller code."] + } +} +``` +```` + +## Format Rules + +These are non-negotiable. Every endpoint file must comply. + +1. **One endpoint per file.** Each `.md` file documents exactly one HTTP method + route combination. Filtered list variants (by status, by scheduleId, etc.) are NOT separate files — they are query parameters within the single `all-{resources}.md` file. +2. **Top-level heading is `#` (H1).** Section headings are `##` (H2). No H3 or deeper inside endpoint files. +3. **Section presence is conditional, section ORDER is not.** Sections always appear in the order shown in the template. Omit a section entirely if it doesn't apply. +4. **Table/JSON parity.** Every field in a Sample Response/Request must have a corresponding row in its Attributes/Body table, and vice versa. The table and the JSON must be a 1:1 match. +5. **Nesting notation:** `field` for top-level, `parent.child` for nested objects, `items[].field` for array items, `items[].parent.child` for nested fields inside arrays. +6. **Type column values:** `string`, `integer`, `boolean`, `number`, `string (GUID)`, `string (ISO 8601)`, `array[string]`, `array[object]`, `object`. Be specific — prefer `string (GUID)` over `string` when the value is a GUID. +7. **Realistic sample data.** Use names, dates, and IDs plausible for a US financial institution workload automation environment. No "foo", "bar", "test", or "example.com". +8. **No cross-references between files.** Each file is self-contained. +9. **camelCase JSON keys** matching `[JsonProperty]` attributes in DTOs. +10. **No commentary, design notes, or explanatory prose.** These are strict reference documents. + +## mkdocs.yml Nav Registration + +After creating an endpoint file, add it to the `nav` section of `mkdocs.yml` in **both** locations: + +1. Under `API > API Reference > {Resource Group}` +2. Under `Reference > API Reference > {Resource Group}` + +If the resource group doesn't exist yet, create it in both locations. Group name = plural resource noun (e.g., "Jobs", "Schedules", "Agents"). Place the new group alphabetically among existing groups. + +Nav entry format: `{Display Name}: api/reference/{filename}.md` + +## Requirements + +1. Read EVERY controller and DTO. Use actual field names from `[JsonProperty]` attributes for JSON keys. +2. Document EVERY endpoint. One file per endpoint. No endpoint may be skipped. +3. Every file MUST use the template for its HTTP method exactly. No freeform paragraphs. +4. Response Attributes tables MUST document every field in the Sample Response using dot/bracket notation for nesting. +5. Sample Responses MUST be complete, realistic JSON — not truncated, not placeholder. +6. Request Body tables MUST mark Required yes/no by reading the controller validation code. Add validation constraints to the Description column. +7. Start with the API collection or Swagger/OpenAPI spec to enumerate endpoints, then read source code for every detail. diff --git a/.claude/skills/technical-writer/resources/opcon-documentation-standards.md b/.claude/skills/technical-writer/resources/opcon-documentation-standards.md new file mode 100644 index 0000000..1aa3bb7 --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-documentation-standards.md @@ -0,0 +1,724 @@ +# Documentation Standards + +Writing and formatting rules for all OpCon documentation. These standards are the single source of truth for style, formatting, and procedural writing decisions. + +**Primary references (in order of authority):** + +1. This document +2. [Merriam-Webster](https://www.merriam-webster.com/) — spelling +3. [Chicago Manual of Style](https://www.chicagomanualofstyle.org/) — general grammar and punctuation +4. [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/) — technical writing, UI, and procedures + +When this document conflicts with an external reference, this document takes precedence. + +--- + +## Core Principles + +- Write for **customers**, not internal teams. +- Be **clear, concise, and consistent**. +- Prioritize **accuracy and completeness** over cleverness. +- Never publish documentation for features that are **not generally available**. +- Assume customers operate in **regulated environments**. +- Be explicit about outcomes and side effects. +- Always describe what success looks like (messages, state changes). + +## Front Matter + +Front matter is the first element of every page. Complete it before writing content. + +Every markdown documentation file must include YAML front matter between +`---` fences at the top of the file. Front matter provides metadata that +serves two purposes: it enables Docusaurus to generate accurate search +results, navigation, and page descriptions, and it gives the AI immediate +context about any page before reading the content. + +### Required Fields + +| Field | Required | Description | +|---|---|---| +| `title` | Yes | The page title, matching the H1 heading. Used by Docusaurus for navigation and browser tab display. | +| `description` | Yes | A one-sentence summary of what the page covers and why it matters. Written for the reader, not the search engine. Should state the value or goal, not just the topic. | +| `tags` | Yes | A list of tags identifying the page's audience, documentation type, and feature area. See Tag Vocabulary below. | + +### Tag Vocabulary + +Use the following controlled vocabulary for tags. Every page must have +at least one tag from each category. + +**Documentation type** (one per page): +`Conceptual`, `Procedural`, `Reference` + +**Audience role** (one or more per page): +`System Administrator`, `Automation Engineer`, `Application Owner`, `Operations Staff`, `Business Analyst`, `Compliance Team` + +**Feature area** (one or more per page): +`Jobs`, `Schedules`, `Agents`, `Frequencies`, `Events`, `Thresholds`, +`Notifications`, `Reports`, `System Configuration`, +`API`, `Getting Started`, `Installation`, `Upgrade`, `Solution Manager` + +### Template + +```yaml +--- +title: Add a Job to a Schedule +description: "Add a new automated job to an existing schedule so OpCon can build and submit it for execution." +tags: + - Procedural + - Automation Engineer + - Jobs +--- +``` + +### Guidelines + +- The `description` field should be a complete sentence, enclosed in + quotes if it contains colons or special characters +- Tags are case-sensitive — use the exact values listed above +- If a page serves multiple audiences, include all applicable role tags +- If a page spans multiple feature areas, include all applicable area tags +- Do not include tags that are only tangentially related — the tag should + reflect what the page is primarily about +- When creating a new page, add front matter before writing any content +- When reviewing an existing page, verify that front matter is present, + accurate, and uses the controlled vocabulary + +--- + +## Language and Grammar + +- Use **second person**: "you," not "we" + > **Exception:** Pages where Continuous is describing its own processes + > (e.g., how connectors are developed, how data accuracy is ensured) + > may use first person ("we") because the company is the subject. This + > should be rare — most documentation is instructional and should use + > second person. +- Use **active voice**, especially in procedures +- Use **imperative verbs** in instructions: "Select," "Enter," "Go to" +- Follow **US English** spelling and punctuation +- Use the **Oxford (serial) comma** +- One idea per sentence; prefer short sentences over compound ones + +--- + +## Action Verbs + +Use the following decision tree for every user interaction. There are no exceptions. + +``` +Is the user navigating to a menu? → "Go to" +Is the user pressing a physical key? → "Press" +Is the user running a job, query, or script?→ "Run" +Is the user deselecting an option? → "Clear" +Is the user typing into a field? → "Enter" +Is the user opening a context menu? → "Right-click" +Everything else (buttons, options, tabs, + links, fields, list selections) → "Select" +``` + +### Quick Reference + +| Action | Verb | Example | +|---|---|---| +| Menu navigation | Go to | Go to the **Administration** menu and select **Job Master**. | +| Button | Select | Select the **Export** button. | +| Option (checkbox) | Select / Clear | Select the **Allow Multi-Instance** option. | +| List selection | Select + pick | Select the **Frequency** field and pick **Daily** from the list. | +| Tab | Select | Select the **Frequency** tab. | +| Link | Select | Select the **Schedules** link. | +| Field entry | Enter | In the **Job Name** field, enter the job name. | +| Keyboard key | Press | Press the **Enter** key. | +| Context menu | Right-click | Right-click the **SMA OpCon** service and select **Start**. | +| Job or query | Run | Run the job. | +| Deselecting | Clear | Clear the **Allow Multi-Instance** option. | + +### Banned Verbs + +Never use the following verbs in documentation: + +- **click** — use "Select" +- **hit** — use "Press" for keys, "Select" for UI elements +- **execute** — use "Run" +- **check / uncheck** — use "Select" / "Clear" +- **turn on / turn off** — use "Select" / "Clear" +- **navigate to** — use "Go to" +- **launch** — use "Open" for applications or "Start" for services + +### Negative Examples + +``` +✅ Select the **Save** button. +❌ Click the Save button. +❌ Click **Save**. + +✅ Go to the **Administration** menu and select **Job Master**. +❌ Navigate to Administration > Job Master. +❌ Click on the Administration menu. + +✅ Select the **Allow Multi-Instance** option. +❌ Check the Allow Multi-Instance checkbox. +❌ Turn on the Allow Multi-Instance toggle. + +✅ Select the **Frequency** field and pick **Daily** from the list. +❌ Click the Frequency dropdown and choose Daily. +❌ Select the **Frequency** drop-down and pick **Daily**. + +✅ Right-click the **SMA OpCon** service and select **Start**. +❌ Click on the SMA OpCon service and select Start. +❌ Right-click on the service. (Do not use "right-click on" — use "right-click" without "on".) + +✅ Right-click the default website and select **Add Application**. +❌ Right-click on the default website and click Add Application. +``` + +--- + +### Additional Notes + +The word "right-click" is the ONE exception to the ban on "click" in +documentation. It is permitted because: + +- There is no alternative verb that clearly communicates opening a + context menu ("Open the context menu for..." is wordy and unfamiliar + to the admin audience) +- The admin guide legitimately requires right-click instructions for + Windows Server, IIS, and service management tasks +- The pattern "Right-click [element] and select [option]" is concise, + unambiguous, and consistent with the existing verb style + +Rules for using "right-click": +- Always hyphenate: "right-click" not "right click" +- Never follow with "on": "Right-click the **service**" not "Right-click on the service" +- Always pair with "and select" for the menu option that follows +- Bold the target element and the menu option +- Only use for actual context menus — do not use for any other purpose + +## UI Element References + +| Element | How to Refer to It | Example | +|---|---|---| +| Button | Label + "button" | Select the **Save** button. | +| Checkbox | Label + "option"; select/clear | Select the **Allow Multi-Instance** option. | +| Radio button | Label + "option" | Select the **Daily** option. | +| Drop-down / list | Use "list", never "drop-down" | Select **Daily** from the list. | +| Field | Exact label + "field" | In the **Job Name** field, enter the value. | +| Text area (large, with formatting) | Label + "area" | Enter the description in the **Documentation** area. | +| Tab | Tab name only | Select the **Frequency** tab. | +| Menu bar item | "Go to" + menu name | Go to the **Administration** menu and select **Job Master**. | +| Navigation menu | "menu" only, no "navigation" | Select **General Settings** from the menu on the left. | +| Icon | Do NOT use the word "icon"; treat as a button | Select the **Settings** button. | +| Hamburger menu | Never say "hamburger"; use label or "menu button" | Select the **OpCon** button in the top left corner. | +| Ellipsis button | Tooltip name + (...) | Select the **More actions** (...) button. | +| Expander arrow | Label + appropriate element; never say "arrow" or "drop-down arrow" | Select the **Frequency** button and pick **Add** from the list. | + +### Banned UI Terminology + +Never use these terms in documentation: + +- **drop-down** (any variation) — use "list" or "field" +- **icon** — treat as a button if it performs an action +- **checkbox** — use "option" +- **radio button** — use "option" +- **hamburger** — use label or "menu button" +- **arrow** or **drop-down arrow** — use the label + appropriate element +- **text box** — use "field" or "area" +- **menu item** — refer to the item by name +- **navigation** (as a noun for a menu) — use "menu" + +--- + +## Menu Paths + +For simple sequential menu selections, use angle brackets with spaces. Bold each label individually. Do **not** bold the angle brackets. + +``` +✅ Select **Administration** > **Job Master** > **Frequencies**. +❌ Select **Administration > Job Master > Frequencies**. +❌ **Administration > Job Master > Frequencies** +``` + +Only use angle bracket paths for simple sequences within the same element (e.g., the same menu). For more complex flows, use separate numbered steps. + +--- + +## Formatting + +### Headings and Titles + +- Use **sentence case** for all titles and headings +- Do not create new styles or override platform defaults + +### Bold + +- **Bold** all UI element names that users interact with (buttons, fields, tabs, menus, options) +- Do not bold angle brackets in menu paths +- Do not bold risk callout labels beyond the specified format (NOTE:, CAUTION:, WARNING:) + +UI element names must match the product **exactly** as displayed — +including capitalization. Never apply sentence case, title case, or +any other casing change to a UI element name. + +✅ Select the **Job Build Status** tab. +✅ Select the **Add Frequency** button. +✅ Go to the **Administration** menu. + +❌ Select the **Job build status** tab. +❌ Select the **add frequency** button. +❌ Go to the **administration** menu. + +Sentence case applies to headings and titles you write — not to +UI labels you reference. + +### Code Font + +- Use `code font` for code, commands, file paths, system values, and configuration settings +- Example: Enter `C:\ProgramData\OpConxps\` in the path field. + +### Lists + +- **Numbered lists** → sequential or ordered steps (procedures) +- **Bulleted lists** → unordered or descriptive content +- Do **not** use periods at the end of bulleted list items +- **Do** use periods at the end of numbered procedural steps +- Introduce every list with a heading, complete sentence, or a fragment ending with a colon + +### Dates + +- Use unambiguous format: **MM/DD/YYYY** + +--- + +## Procedural Instructions + +Procedures explain **how to do something** and must be predictable and scannable. + +### Required Rules + +1. Open with: "To [accomplish goal], complete the following steps:" +2. Use **numbered lists** for all steps +3. **One action per step** — do not combine actions unless selecting nested menu items via angle brackets +4. End the procedure with a **result statement** describing what the user sees or what changed +5. Break procedures longer than **~10 steps** into linked sections +6. Reuse wording and structure — **repetition improves usability** + +### Step Structure + +```markdown +To [accomplish goal], complete the following steps: + +1. Go to the **Administration** menu and select **Job Master**. +2. Select the schedule. +3. Select the **Add** button. The Job Master Details page is displayed. +4. In the **Job Name** field, enter the job name. +5. Select the **Save** button. The job is added to the schedule. +``` + +### Sub-Steps + +Use letters for nested actions within a step: + +```markdown +1. Configure the frequency: + a. Select the **Frequency** tab. + b. In the **Frequency Name** field, enter the name. + c. Select the **Save** button. +``` + +### Optional Steps + +Mark optional steps explicitly: + +```markdown +4. (Optional) Select the **Allow Multi-Instance** option. +``` + +### Tables in Procedures + +Use tables when users must choose between options within a step. + +- Introduce the table in the step text +- Indent the table to align with the step it belongs to +- Always explain the **consequences** of each option + +```markdown +2. Select one of the following options: + + | Option | Description | + |---|---| + | Copy a Job | Creates a new job by copying an existing one. Frequencies, dependencies, and events are duplicated. | + | Create a New Job | Creates a new job from scratch. You will need to configure all settings manually. | + +3. Select the **Save** button. +``` + +### Linking to Other Procedures + +When a procedure references steps documented elsewhere, link rather than duplicate: + +```markdown +1. [From the Schedule list], select the **Add Job** button. +``` + +This accommodates both experienced users (who skip the link) and new users (who follow it). + +--- + +## Pattern Library + +These patterns cover the most common documentation scenarios. Match each new task to the closest pattern. + +### Pattern 1: Simple Export + +```markdown +To export the report, complete the following steps: + +1. Go to the **Reports** menu and select **Scheduled Jobs**. +2. Select the schedule. +3. Select the **Export** button and pick **Excel** from the list. The report is downloaded. +``` + +### Pattern 2: Configuration / Settings + +```markdown +To configure SMTP settings, complete the following steps: + +1. Go to the **Administration** menu and select **System Settings**. +2. In the **SMTP Server** field, enter the server address. +3. In the **Port** field, enter the port number. +4. (Optional) Select the **Use SSL** option. +5. Select the **Save** button. The settings are saved. +``` + +### Pattern 3: Search and Select + +```markdown +To find a job, complete the following steps: + +1. Go to the **Administration** menu and select **Job Master**. +2. In the **Search** field, enter the job name. +3. Press the **Enter** key. +4. Select the job from the results. The Job Master Details page is displayed. +``` + +### Pattern 4: Create Then Configure + +```markdown +To add a job, complete the following steps: + +1. [From the Job Master list], select the **Add** button. The Job Master Details page is displayed. +2. Select one of the following options: + + | Option | Description | + |---|---| + | Copy a Job | Creates a new job by copying an existing one. | + | Create a New Job | Creates a new job using a connector. | + +3. Select the **Save** button. The job is added to the schedule. +4. [Add a frequency to the job]. +``` + +### Pattern 5: Multi-Option Step + +```markdown +3. Select a format: + - To export as PDF: Select **PDF** from the list. + - To export as Excel: Select **Excel** from the list. +``` + +### Pattern 6: Long Procedure (Broken Into Sections) + +When a procedure exceeds ~10 steps, break it into named sections and link between them: + +```markdown +## Step 1 — Download installation files + +1. Log into Solution Manager as an Administrator. +2. Go to the **Administration** menu and select **Upgrade**. +3. Select each of the three download links. +4. Save the files to the Install Files folder. + +## Step 2 — Stop the service + +1. Open the Windows Services console. +2. Right-click the **SMA OpCon** service and select **Stop**. + +## Step 3 — Run the database migrator +... +``` + +--- + +## Risk Callouts + +Use callouts sparingly and intentionally. Three tiers: + +| Level | Format | Use For | +|---|---|---| +| Note | **NOTE:** followed by the text | Helpful, non-critical information — tips, clarifications, reminders | +| Caution | **CAUTION:** followed by the text | Risk of data, system, or configuration issues | +| Warning | **WARNING:** in all caps, bold | High risk of serious damage or data loss | + +### In Zensical / MkDocs Markdown + +Use admonition syntax: + +```markdown +!!! note + This information can be found at help.smatechnologies.com. + +!!! warning + Not completing a backup prior to these steps could result in data loss. +``` + +### In Plugin Instructions (C# Inline) + +Use heading syntax indented under the relevant step: + +```csharp +.AppendLine("3. Select **Reset My Security Token**.") +.AppendLine(" ###### Tip: The token is sent to your registered email.") +``` + +--- + +## Images + +Include images **only when they add clarity** — specifically when the step involves a UI element that the reader must visually identify to proceed. + +- Use **PNG** format +- Provide **alt text** for every image +- Maintain **aspect ratio** when resizing +- **Indent** images to align with their related step in a procedure + +--- + +## Content Reuse + +- If a procedure is identical across guides, write it once and link to it from each guide +- If a procedure is similar but has role-specific differences, write separate versions and note the differences +- Never copy-paste content between pages — duplicated content creates maintenance debt +- Use "Related topics" links to connect shared concepts across guides + +--- + +## Release Notes + +Release notes are reference documentation. Customers scan them to find what changed and how it affects them. Every release gets one release notes page. + +### Structure + +| Section | Required | Description | +|---|---|---| +| Version and date | Yes | Version number and release date as the page title and subtitle | +| Summary | Yes | 1–3 sentences describing the release theme — what this release is about at a high level | +| New features | When applicable | Features that did not exist before this release | +| Improvements | When applicable | Enhancements to existing features | +| Bug fixes | When applicable | Issues that were resolved | +| Known issues | When applicable | Outstanding issues with workarounds | +| Upgrade notes | When applicable | What Administrators must do before or after upgrading | + +### Organizing Entries + +Group entries by **feature area**, not by role. Use headings that match the product's navigation so customers can find what's relevant to them: + +- Jobs +- Schedules +- Agents +- Frequencies +- Events +- Thresholds +- Notifications +- Reports +- System Configuration +- API +- Solution Manager + +Within each feature area, list entries in order of impact: new features first, then improvements, then bug fixes. + +### Entry Guidelines + +Each entry follows this pattern: + +``` +**[Past-tense verb] [what changed].** [Why it matters or what the customer sees.] +``` + +Rules: +- Start each entry with a **past-tense verb**: Added, Fixed, Updated, Removed, Improved, Redesigned, Resolved +- State **what changed** in customer-facing terms (consult glossary.md) +- Follow with **why it matters** or what the customer experience is now +- One entry per user-visible change — do not document internal refactors +- Keep each entry to 1–2 sentences +- Do not include Jira ticket numbers or internal references in customer-facing release notes + +### Template + +```markdown +# OpCon [version] + +**Released:** [MM/DD/YYYY] + +[1–3 sentence summary of the release theme.] + +## New features + +### [Feature area] + +- **Added [feature].** [Why it matters or what the customer sees.] +- **Added [feature].** [Description.] + +### [Feature area] + +- **Added [feature].** [Description.] + +## Improvements + +### [Feature area] + +- **Improved [what changed].** [What the customer experience is now.] +- **Updated [what changed].** [Description.] + +## Bug fixes + +### [Feature area] + +- **Fixed an issue where [description of the problem].** [What happens now.] + +## Known issues + +- **[Description of the issue].** Workaround: [steps or explanation.] + +## Upgrade notes + +- [What Administrators must do before or after upgrading.] +``` + +### Example + +```markdown +# OpCon 26.0 + +**Released:** 03/15/2026 + +OpCon 26.0 introduces enhanced frequency management, Solution Manager +performance improvements, and several fixes to the job dependency workflow. + +## New features + +### Frequencies + +- **Added frequency preview.** You can now preview which dates a frequency + will generate before saving it, allowing you to verify holiday and + blackout calendar interactions before the schedule is built. + +### Schedules + +- **Added bulk schedule build.** You can now trigger a manual build for + multiple schedules at once from the Schedule list instead of building + each schedule individually. + +## Improvements + +### Agents + +- **Improved agent communication retry logic.** OpCon now retries failed + agent communication attempts up to three times before marking the agent + as unavailable, reducing false disconnection alerts. + +### Reports + +- **Updated the Job Execution History report to include threshold values.** + Each job now shows the threshold state at execution time, which simplifies + audit documentation for automated decision points. + +## Bug fixes + +### Jobs + +- **Fixed an issue where jobs with multi-instance configurations did not + display all instances on the Operations dashboard.** All instances now + appear correctly regardless of how the job was triggered. + +### Frequencies + +- **Fixed an issue where annual frequencies were not correctly applying + holiday calendar offsets.** Frequencies now apply calendar offsets as + configured. + +## Upgrade notes + +- Back up your database before upgrading. Refer to + [Backup and Restore](../admin-guide/backup-restore.md) for + instructions. +- After upgrading, go to **Administration** and select + **Health Check** to verify all components are running correctly. +``` + +### What NOT to Include + +- Internal ticket numbers (OC-1010, IDEA-1229, etc.) +- Developer-facing details (class names, database schema changes, refactors) +- Changes that are not visible to customers +- Marketing language or superlatives ("exciting new feature," "game-changing update") +- Future plans or roadmap items ("coming soon," "in a future release") + +### Tone + +Release notes serve all roles simultaneously. Write for the **least technical audience** while including enough detail for technical readers: + +- Use plain language — avoid jargon unless it's standard product terminology +- Be specific about what changed — "Updated the Job Execution History report" not "Made report improvements" +- Be honest about bug fixes — describe what was wrong and what's fixed +- Keep it scannable — customers should find what matters to them in seconds + +--- + +## Pre-Flight Checklist + +Before finalizing any documentation, verify: + +### Content + +- [ ] Feature is generally available +- [ ] Uses customer-facing terminology (consult glossary.md) +- [ ] Appropriate for the target audience role (consult learner-roles.md) +- [ ] Risks are clearly called out at the appropriate tier + +### Formatting + +- [ ] All UI element names are **bold** +- [ ] UI labels match the product exactly +- [ ] No bulleted list items end with periods +- [ ] All numbered procedural steps end with periods +- [ ] Angle brackets in menu paths are not bolded +- [ ] Code, commands, and paths use `code font` +- [ ] Dates use MM/DD/YYYY format +- [ ] Headings use sentence case + +### Procedures + +- [ ] Opens with "To [goal], complete the following steps:" +- [ ] One action per step +- [ ] Steps are numbered sequentially +- [ ] Ends with a result statement +- [ ] No procedure exceeds ~10 steps without a section break +- [ ] Tables in procedures explain consequences of each option + +### Banned Terms + +- [ ] No instance of "click" +- [ ] No instance of "execute" (use "run") +- [ ] No instance of "hit" +- [ ] No instance of "check/uncheck" or "turn on/turn off" +- [ ] No instance of "navigate to" (use "go to") +- [ ] No instance of "drop-down" (use "list" or "field") +- [ ] No instance of "icon" (treat as button) +- [ ] No instance of "checkbox" or "radio button" (use "option") +- [ ] No instance of "hamburger" +- [ ] No instance of "text box" (use "field" or "area") +- [ ] No instance of "client" (use "customer") +- [ ] No instance of "launch" (use "open" or "start") + +--- + +**When in doubt:** Follow the Microsoft Writing Style Guide and optimize for clarity over brevity. diff --git a/.claude/skills/technical-writer/resources/opcon-documentation-types.md b/.claude/skills/technical-writer/resources/opcon-documentation-types.md new file mode 100644 index 0000000..c3e6a27 --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-documentation-types.md @@ -0,0 +1,299 @@ +# Documentation Types + +Every documentation page falls into one of three types. Before writing or reviewing a page, identify its type and follow the corresponding structure. If a page combines types (e.g., a conceptual overview followed by a procedure), use the structure for each section independently. + +--- + +## How to Identify the Type + +``` +What is the reader trying to do? + + "I need to understand something." → Conceptual + "I need to do something." → Procedural + "I need to look something up." → Reference +``` + +--- + +## 1. Conceptual Documentation + +**Purpose:** Build understanding of broader ideas, principles, or how things connect together. Helps readers understand the bigger picture — what features are for, why something works a certain way, and when they would use it. + +**When to use:** Overviews, introductions, feature explanations, "how it works" topics, architecture descriptions, and "why" explanations. + +### Structure + +| Section | Required | Description | +|---|---|---| +| Title | Yes | Clear, descriptive title using sentence case. Should answer "what is this about?" | +| Introduction | Yes | 1–3 sentences explaining what this topic covers and why it matters. State the value to the reader upfront. | +| Body | Yes | The explanation itself. Organize by subtopic, not by chronological order. Use headings to break up distinct concepts. | +| Diagrams or examples | When helpful | Use diagrams, analogies, or real-world examples to make abstract concepts concrete. | +| How it connects | When applicable | Explain how this concept relates to other features or workflows. Link to related procedural or reference pages. | +| Related topics | When applicable | Links to related pages. | + +### Guidelines + +- Lead with **why it matters**, not what it is +- Explain concepts in terms the target audience already understands (consult learner-roles.md for assumed knowledge) +- Use concrete examples from a financial institution context +- Do not include step-by-step instructions — link to the procedural page instead +- Keep paragraphs short (3–5 sentences) +- Use headings to make the content scannable + +### Template + +```markdown +# [Topic Name] + +[1–3 sentence introduction: what this is and why it matters to the reader.] + +## [Subtopic 1] + +[Explanation with context and examples.] + +## [Subtopic 2] + +[Explanation with context and examples.] + +## How [Topic] Works with [Related Feature] + +[Explain connections to other features or workflows.] + +**Related topics:** + +- [Related procedural page] +- [Related reference page] +``` + +### Example + +```markdown +# Frequencies + +Frequencies define when a job or schedule is eligible to run. When a job +is added to a schedule, one or more frequencies determine which days and +times OpCon will build and submit that job for execution. + +## Why frequencies matter + +Without a frequency, OpCon has no rules for when to run a job. A correctly +configured frequency ensures the job runs on the right days, at the right +times, and skips holidays or blackout periods automatically — reducing +manual intervention and preventing missed processing windows. + +## How frequencies work with schedules + +When OpCon builds the daily schedule, it evaluates each job's frequency +against the current date. Jobs whose frequency conditions are met are added +to that day's schedule. Jobs that do not meet the frequency conditions are +not built for that day. + +**Related topics:** + +- [Add a Frequency to a Job] +- [Configure Holiday Calendars] +``` + +--- + +## 2. Procedural Documentation + +**Purpose:** Explain how to do something in an intentionally sequential order using step-by-step instructions. + +**When to use:** Any task the reader needs to complete — installing, configuring, creating, importing, exporting, or any workflow that has a defined sequence of actions. + +### Structure + +| Section | Required | Description | +|---|---|---| +| Title | Yes | Starts with a verb or describes the task clearly. Example: "Add a Job to a Schedule" or "Configure Agent Communication Settings" | +| Introduction | Yes | 1–2 sentences stating what the procedure accomplishes and when/why the reader would do it. | +| Prerequisites | When applicable | What must be true or completed before starting. Use a note or admonition. | +| Steps | Yes | Numbered, sequential, one action per step. Follows all rules in documentation-standards.md. | +| Result statement | Yes | Final step or sentence describing what the reader sees or what changed. | +| Related topics | When applicable | Links to next steps or related procedures. | + +### Guidelines + +- Follow all procedural rules in documentation-standards.md (action verbs, one action per step, ~10 step limit, etc.) +- State the goal before the steps: "To [accomplish goal], complete the following steps:" +- Put prerequisites before the steps, not buried within them +- End with a result statement so the reader knows they succeeded +- Link to other procedures rather than duplicating steps +- Use tables within steps when the reader must choose between options + +### Template + +```markdown +# [Task Name] + +[1–2 sentences: what this procedure accomplishes and when to use it.] + +!!! note "Prerequisite" + [What must be completed before starting.] + +To [accomplish goal], complete the following steps: + +1. [First action.] +2. [Second action.] +3. [Third action.] The [result] is displayed. + +**Related topics:** + +- [Next step or related procedure] +``` + +### Example + +```markdown +# Add a Job to a Schedule + +Use this procedure to add a new automated job to an existing schedule. +Repeat this procedure for each job that needs to be added. + +!!! note "Prerequisite" + The schedule must exist before adding jobs. See [Create a Schedule]. + +To add a job, complete the following steps: + +1. Go to the **Administration** menu and select **Job Master**. +2. In the **Schedule** list, select the schedule. +3. Select the **Add** button. The Job Master Details page is displayed. +4. In the **Job Name** field, enter the job name. +5. In the **Job Type** list, select the job type. +6. Select the **Save** button. The job is added to the schedule. + +**Related topics:** + +- [Add a Frequency to a Job] +- [Configure Job Dependencies] +``` + +--- + +## 3. Reference Documentation + +**Purpose:** Provide factual information that readers need to look up quickly. Organized for scanning, not reading start to finish. + +**When to use:** UI element descriptions, field/setting definitions, report descriptions, plugin lists, API documentation, glossaries, system requirements, and any factual lookup content. + +### Structure + +| Section | Required | Description | +|---|---|---| +| Title | Yes | Names the reference subject clearly. Example: "Standard Reports" or "Hardware and Software Requirements" | +| Introduction | Yes | 1–2 sentences explaining what information is provided and how it's organized. | +| Reference content | Yes | Tables, definition lists, or organized sections. Information should be sorted logically (alphabetically, by function, by category, or in the order it appears in the application). | +| Notes or caveats | When applicable | Important context about limitations, special cases, or version differences. | + +### Guidelines + +- Optimize for **scanning**, not reading +- Use tables as the primary format — they are faster to scan than prose +- Sort content in the order that makes the most sense for lookup (alphabetical, by category, by UI order) +- Keep descriptions factual and concise — one to two sentences per item +- Do not include step-by-step instructions — link to the procedural page instead +- Include all items completely — reference docs must not have gaps + +### Template + +```markdown +# [Reference Subject] + +[1–2 sentences: what information is provided here and how it's organized.] + +## [Category 1] + +| [Column 1] | [Column 2] | [Column 3] | +|---|---|---| +| Item | Description | Notes | + +## [Category 2] + +| [Column 1] | [Column 2] | [Column 3] | +|---|---|---| +| Item | Description | Notes | +``` + +### Example + +```markdown +# Standard Reports + +The Standard Reports section provides pre-configured reports related +to jobs, schedules, agents, and thresholds. Reports are available in +PDF and/or Excel formats. + +## Job Reports + +| Report | Description | Formats | +|---|---|---| +| Job Execution History | All job runs within a selected date range, including start time, end time, exit code, and agent. | PDF, Excel | +| Failed Jobs Summary | All jobs that ended in a failed status within the selected period, with exit codes and job details. | PDF, Excel | +| Job Dependency Map | All dependencies configured for a selected job or schedule. | PDF | + +## Schedule Reports + +| Report | Description | Formats | +|---|---|---| +| Schedule Build Summary | A record of all schedule builds for a selected date range, including build status and job counts. | PDF, Excel | +| On-Hold Schedules | All schedules currently placed on hold, with the date and user who initiated the hold. | PDF, Excel | +``` + +--- + +## Combining Types on a Single Page + +Some pages naturally combine types. When this happens: + +1. **Identify the primary type** — this determines the page's overall structure and title +2. **Use clear section breaks** between types — a heading should signal the shift +3. **Keep each section's rules independent** — conceptual sections follow conceptual guidelines, procedural sections follow procedural guidelines + +### Common Combinations + +| Primary Type | Secondary Type | Example | +|---|---|---| +| Conceptual | Procedural | Feature overview followed by "Getting Started" steps | +| Procedural | Reference | Setup procedure followed by a settings/options reference table | +| Conceptual | Reference | Explanation of a concept followed by a terminology or comparison table | + +### What NOT to Do + +- Do not embed a full procedure inside a conceptual explanation — link to it instead +- Do not scatter reference tables throughout a procedure — put them after the steps or in a separate section +- Do not write a reference page in paragraph form — use tables and lists + +--- + +## Common Mistakes + +### Conceptual page that should be procedural +❌ "The job build process begins when you select the Build button and +then choose the date range..." (narrative description of steps) +✅ Link to the procedural page instead + +### Procedural page with buried prerequisites +❌ Step 7: "Note: You must have admin access to complete this step." +✅ State prerequisites before the steps begin + +### Reference page written as prose +❌ "The Job Execution History report shows the job name, start time, and +exit code. It also includes the agent name and run duration..." +✅ Use a table with columns for Report, Description, and Formats + +--- + +## Connecting Types to Audience + +When writing a page, combine the documentation type (from this file) with the audience role (from opcon-learner-roles.md): + +| Step | Question | Source | +|---|---|---| +| 1 | Who is reading this? | opcon-learner-roles.md | +| 2 | What are they trying to do? | This file (opcon-documentation-types.md) | +| 3 | How should I write it? | opcon-documentation-standards.md | + +The **audience** determines tone, terminology depth, and assumed knowledge. The **type** determines structure and organization. The **standards** determine formatting and style. All three work together. diff --git a/.claude/skills/technical-writer/resources/opcon-glossary.md b/.claude/skills/technical-writer/resources/opcon-glossary.md new file mode 100644 index 0000000..b6d0b37 --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-glossary.md @@ -0,0 +1,570 @@ +# OpCon Terminology Glossary + +> **Source:** Continuous OpCon Documentation | Last Updated: March 2026 + +--- + +## How to Use This Glossary + +Within the world of workload automation and banking operations, the same concept can be described in many different ways. This glossary provides the preferred terminology used at Continuous for OpCon. Use it as the definitive reference for all customer-facing and internal communications. + +This glossary is organized into two sections: + +- **Customer-facing terms** (the main alphabetical glossary) — use these terms in all documentation, UI copy, and customer communication +- **Internal and legacy terms** (at the end) — these terms appear in source code or older documentation only. Never use them in customer-facing output. They are included so the AI can recognize them when encountered in source material and map them to the correct customer-facing term. + +### Notation Key + +| Notation | Meaning | +|----------|---------| +| **Words customers might use** | Alternative terms customers may use in conversation | +| **Do not use** | Terms to avoid in documentation and customer communication | +| **DRAFT** | Definition is still being revised or awaiting approval | +| **INTERNAL** | Internal-only term; not for customer-facing communication | +| **LEGACY** | Old term replaced by a current customer-facing term; appears in source code or historical content | + +--- + +## A + +### Agent + +*noun* + +The software component installed on a machine that communicates with OpCon, receives job instructions, executes jobs, and reports results back to OpCon. Each agent is associated with one machine definition in OpCon. + +**Words customers might use:** machine, server, LSAM + +**Do not use:** LSAM (in user-facing text), server, host (as a synonym for agent) + +**See also:** Machine, Machine Group + +--- + +### Audit + +*noun* + +An independent examination to assess the quality and effectiveness of internal controls, risk management, and compliance initiatives in an organization. + +--- + +### Audit Log + +*noun* + +A list of user or system activities within an application. Activities are ordered chronologically by the date and time they occurred. + +--- + +### Audit Trail + +*noun* + +A chronological record of activities that can be used to reconstruct — from start to finish — a sequence of events related to a specific operation, procedure, or event. + +--- + +### Authentication + +*noun* + +Verifying that a user or system is who or what it claims to be and that it is permitted to access an application or resource. + +--- + +### Authorization + +*noun* + +The process of determining what a user or system is permitted to do within an application. + +--- + +### Automation Engineer + +*noun* + +A role within OpCon responsible for building and maintaining schedules, jobs, frequencies, and dependencies. See [opcon-learner-roles.md](opcon-learner-roles.md) for full audience guidance including knowledge domains, tone, assumed knowledge, and scope boundaries. + +--- + +## B + +### Baseline + +*noun* + +A set of information that has been formally verified and documented as of a specific point in time. Often used as a starting point for tracking changes over time. + +--- + +### Batch User + +*noun* + +A user account defined on an agent machine under which OpCon executes jobs. Each job definition specifies which batch user will run the job. Batch users must be defined in OpCon before they can be assigned to jobs. + +**Do not use:** service account (as a synonym for batch user in OpCon context) + +--- + +### Business Analyst + +*noun* + +A role within OpCon responsible for documenting automation requirements and bridging communication between Application Owners and Automation Engineers. See [opcon-learner-roles.md](opcon-learner-roles.md) for full audience guidance including knowledge domains, tone, assumed knowledge, and scope boundaries. + +--- + +## C + +### Compliance + +*noun* + +The act of following regulatory requirements, standards, and best practices for the secure and controlled operation of automated processes. For financial institutions using OpCon, compliance includes ensuring that automated job processing is documented, auditable, and operating within defined controls. + +--- + +### Compliance Team + +*noun* + +A role within OpCon responsible for reviewing job execution history, audit logs, and reports to verify that automated processes are operating as documented and within regulatory requirements. See [opcon-learner-roles.md](opcon-learner-roles.md) for full audience guidance including knowledge domains, tone, assumed knowledge, and scope boundaries. + +--- + +### Container Job + +*noun* + +A job type that runs a sub-schedule. When a container job runs, OpCon builds and executes all the jobs in the referenced sub-schedule. Container jobs allow schedules to be nested within other schedules. + +**See also:** Sub-Schedule + +--- + +### Control + +*noun* + +Policies, procedures, and mechanisms that govern how automated processes execute and who can modify them. Controls enforce an organization's security and operational policies. Examples include role-based access controls within OpCon and change management procedures for modifying job definitions. + +--- + +## D + +### Daily Schedule + +*noun* + +The instance of schedules and jobs that OpCon builds for a specific calendar date. When OpCon builds the daily schedule, it evaluates each job's frequencies to determine which jobs to include. The daily schedule is distinct from the master job and schedule definitions stored in the Job Master. + +**Words customers might use:** today's schedule, the schedule + +--- + +### Dependency + +*noun* + +A relationship between two jobs that controls execution order. A job with a dependency will not start until the job or jobs it depends on have reached the required status. OpCon supports three dependency types: Requires, After, and Excludes. + +**See also:** Requires Dependency, After Dependency, Excludes Dependency + +--- + +## E + +### Event + +*noun* + +An automated action that OpCon takes in response to a job or schedule status change. Events are defined as part of a job's configuration and can trigger actions such as sending notifications, setting threshold values, calling external APIs, or adding jobs to a running schedule. + +**Do not use:** trigger, action (as synonyms for OpCon Event) + +--- + +### Exit Code + +*noun* + +The numerical return value that a job sends to OpCon when it finishes executing. An exit code of `0` typically indicates success. Non-zero exit codes typically indicate failure. OpCon uses exit codes to determine job status and evaluate dependency conditions. + +**Words customers might use:** return code, error code + +--- + +### Excludes Dependency + +*noun* + +A dependency type that removes a job from the daily schedule if the job it depends on reaches a specified exit code or status. Use an Excludes dependency when a downstream job should not run if an upstream job ends in a certain condition. + +**See also:** Dependency, Requires Dependency, After Dependency + +--- + +## F + +### Frequency + +*noun* + +A named set of rules that defines when a job or schedule is eligible to be built into the daily schedule. Frequencies specify which days of the week, days of the month, or calendar-based patterns a job should run on. A job without a frequency will not be built. + +**Do not use:** trigger, schedule pattern, recurrence rule (as synonyms for frequency) + +--- + +## G + +### Global Property + +*noun* + +A system-wide variable defined in OpCon that can be referenced in job command lines, event parameters, and other fields using the `[[property_name]]` token syntax. Global properties allow common values (such as file paths or environment names) to be defined once and reused across many job definitions. + +**Words customers might use:** system variable, environment variable, property token + +--- + +## H + +### Holiday Calendar + +*noun* + +A named list of specific dates on which certain frequencies are suppressed. When a frequency is configured to respect a holiday calendar, jobs using that frequency will not be built on dates listed in the calendar. Holiday calendars allow one-time exclusions (such as bank holidays) without modifying individual frequency definitions. + +--- + +## J + +### Job + +*noun* + +A single unit of automated work defined in the Job Master. A job specifies what to run, where to run it (agent), who runs it (batch user), when to run it (frequency), and under what conditions it depends on other jobs (dependencies). Jobs belong to schedules. + +**Do not use:** task, process, step (as synonyms for OpCon job) + +--- + +### Job Master + +*noun* + +The repository in OpCon where all job definitions are stored and maintained. Changes made in the Job Master affect future schedule builds but do not change jobs that are already in the daily schedule. + +--- + +### Job Status + +*noun* + +The current state of a job instance in the daily schedule. OpCon assigns a status to each job as it moves through the build, wait, execution, and completion cycle. Key statuses include Qualifying, Waiting, On Hold, Running, Finished OK, Failed, and Cancelled. + +--- + +## M + +### Machine + +*noun* + +The OpCon record that defines a server and its connection settings for agent communication. Each machine record stores the agent type, network address, port, and communication parameters. "Machine" and "Agent" are used interchangeably in OpCon documentation; "machine" typically refers to the OpCon configuration record, while "agent" refers to the software running on the server. + +**See also:** Agent, Machine Group + +--- + +### Machine Group + +*noun* + +A named collection of machines in OpCon. Jobs assigned to a machine group can run on any available machine within the group, enabling load balancing and failover across multiple agents. + +--- + +### Multi-Instance + +*noun* + +A configuration option that allows a job or schedule to run as multiple simultaneous instances. When multi-instance is enabled, the same job or schedule can be built and run more than once at the same time, typically with different property values distinguishing each instance. + +--- + +## O + +### On Hold + +*noun* + +A job or schedule status indicating that the job or schedule has been manually placed in a suspended state and will not run until it is released. Operations Staff use On Hold to temporarily pause automation without canceling it. + +--- + +### Operations Staff + +*noun* + +A role within OpCon responsible for monitoring running schedules and responding to job failures during live processing. See [opcon-learner-roles.md](opcon-learner-roles.md) for full audience guidance including knowledge domains, tone, assumed knowledge, and scope boundaries. + +--- + +### OpCon + +*proper noun* + +A workload automation platform built by Continuous (legacy name: Sycorr) for US financial institutions. OpCon automates, monitors, and manages batch processing across servers, applications, and platforms. + +--- + +## P + +### Principle of Least Privilege + +*noun* + +A security standard that states users and automated processes should have only the minimum access required to perform their intended function. In OpCon, this applies to both user roles within the OpCon interface and batch user accounts used for job execution. + +--- + +## R + +### Requires Dependency + +*noun* + +A dependency type that holds a downstream job until the upstream job reaches the specified exit code or status. The most common dependency type; typically used to ensure a job does not start until a prerequisite job has completed successfully. + +**See also:** Dependency, After Dependency, Excludes Dependency + +--- + +### After Dependency + +*noun* + +A dependency type that releases a downstream job once the upstream job reaches any finished status, regardless of whether it succeeded or failed. Use an After dependency when the downstream job should run after the upstream job finishes but does not depend on the outcome. + +**See also:** Dependency, Requires Dependency, Excludes Dependency + +--- + +### Role-based Access Control + +*noun* + +A method of assigning system permissions to users based on their job role. Within OpCon, role-based access control determines which schedules, jobs, machines, and administrative functions each user can view or modify. + +--- + +## S + +### SAM (Schedule Activity Monitor) + +*noun* + +OpCon's core processing engine. The SAM evaluates job and schedule statuses, resolves dependencies, sends job start instructions to agents, and processes events. The SAM runs as a Windows service on the OpCon server. + +**Do not use:** SAM in user-facing documentation except when specifically referring to the Windows service. Prefer "OpCon" when describing system behavior in general terms. + +--- + +### Schedule + +*noun* + +A named collection of jobs in OpCon. Schedules group related jobs together and define shared settings such as the start time for the schedule build. Jobs within a schedule can have dependencies on each other and on jobs in other schedules. + +**Do not use:** workflow, job stream (as synonyms for schedule) + +--- + +### Schedule Build + +*noun* + +The process by which OpCon generates the daily schedule by evaluating each schedule's and job's frequency definitions against the current date. Schedule builds can happen automatically at a configured time or be triggered manually. + +--- + +### Separation of Duties + +*noun* + +A security principle that requires more than one person to be involved in completing a critical task or process. In OpCon, separation of duties applies to access controls that limit who can create, modify, and release jobs to production. + +--- + +### Single Sign-On (SSO) + +*noun* + +An authentication method that allows a user to log in once and access multiple systems without re-entering credentials. OpCon supports SSO integration with organizational identity providers. + +--- + +### Solution Manager + +*noun* + +The browser-based interface for OpCon. Solution Manager is the primary tool for Automation Engineers, Operations Staff, and System Administrators to configure, monitor, and manage OpCon. + +**Do not use:** web UI, portal, web console (as synonyms for Solution Manager) + +**See also:** Enterprise Manager (legacy) + +--- + +### Sub-Schedule + +*noun* + +A schedule that is nested inside a container job. When OpCon runs the container job, it builds and executes the sub-schedule. Sub-schedules allow complex multi-step workflows to be modularized and reused across different parent schedules. + +**See also:** Container Job + +--- + +### System Administrator + +*noun* + +A role within OpCon responsible for installing, configuring, and maintaining the OpCon environment. See [opcon-learner-roles.md](opcon-learner-roles.md) for full audience guidance including knowledge domains, tone, assumed knowledge, and scope boundaries. + +--- + +## T + +### Threshold + +*noun* + +A named numeric variable in OpCon used for dependency management and flow control. Jobs can be configured to wait until a threshold reaches a specific value before running, and events can increment or decrement threshold values in response to job status changes. + +**Words customers might use:** counter, flag, variable + +--- + +### Token (OpCon API) + +*noun* + +An authentication credential used to make requests to the OpCon REST API. API tokens are generated within Solution Manager and included in the `Authorization` header of each API request. + +--- + +## W + +### Webhook + +*noun* + +A method that allows one system to notify another system when a specific event occurs. OpCon can send webhook notifications when jobs reach certain statuses, enabling integration with external monitoring tools, ticketing systems, and notification platforms. + +--- + +--- + +## Internal and Legacy Terms + +> **Do not use these terms in customer-facing documentation.** They are +> included so the AI can recognize them in source code, internal +> discussions, and legacy content — and map them to the correct +> customer-facing term. + +### Enterprise Manager (EM) + +*noun* — LEGACY + +The legacy Windows-based desktop client for OpCon, replaced by Solution Manager. Enterprise Manager may still appear in older documentation, training materials, and customer installations that have not yet migrated to Solution Manager. + +**In documentation:** Always use **Solution Manager**. Reference Enterprise Manager only when specifically documenting a feature or step that is available exclusively in the legacy client. + +--- + +### LSAM (Legacy Schedule Activity Monitor) + +*noun* — LEGACY + +The legacy term for the agent software installed on machines that communicate with OpCon. LSAM appears throughout older documentation, connector names, and some platform-specific agent types (e.g., MFT LSAM, IBM i LSAM). + +**In documentation:** Use **agent** in all general user-facing text. Reference "LSAM" only when documenting a specific platform agent where the term appears in the product UI or installer. + +--- + +### Operations Center (OC) + +*noun* — INTERNAL + +Continuous's internal operations system used to manage day-to-day customer service activities. Not a customer-facing term. + +--- + +### Plugin + +*noun* — LEGACY / INTERNAL + +Legacy internal code term for what is now called a **Connector** in customer-facing contexts. Appears throughout source code (`*Plugin*.cs`, plugin parameter definitions) but must not appear in customer-facing documentation. + +**In documentation:** Use **Connector**. The term "plugin" may appear in C# source files and internal tooling — translate to "connector" in all customer-facing output. + +--- + +--- + +## Quick Reference: Job Status Values + +| Status | Meaning | +|--------|---------| +| **Qualifying** | OpCon is evaluating whether the job's frequency and start conditions are met | +| **Waiting** | The job's frequency is met but one or more dependencies have not been satisfied | +| **On Hold** | The job has been manually suspended and will not run until released | +| **Running** | The job is currently executing on its assigned agent | +| **Finished OK** | The job completed with the expected exit code | +| **Failed** | The job completed with an unexpected exit code | +| **Cancelled** | The job was manually cancelled before or during execution | +| **Skipped** | The job was manually bypassed for the current day | + +--- + +## Quick Reference: Dependency Types + +| Type | When to Use | Outcome if Condition Is Not Met | +|------|-------------|----------------------------------| +| **Requires** | Downstream job needs upstream job to succeed | Downstream job remains in Waiting status | +| **After** | Downstream job should run after upstream job regardless of outcome | Downstream job remains in Waiting status until upstream job finishes | +| **Excludes** | Downstream job should not run if upstream job reaches a certain status | Downstream job is removed from the daily schedule | + +--- + +## Quick Reference: OpCon User Roles + +| Role | Primary Responsibility | +|------|----------------------| +| **System Administrator** | Install, configure, and maintain OpCon infrastructure | +| **Automation Engineer** | Build and maintain schedules, jobs, frequencies, and dependencies | +| **Operations Staff** | Monitor the daily schedule and respond to job failures | +| **Application Owner** | Own the business processes being automated and validate outcomes | +| **Business Analyst** | Document requirements and bridge business and engineering teams | +| **Compliance Team** | Review execution history and generate audit evidence | + +--- + +## Quick Reference: Key Terminology Rules + +| Correct Term | Do Not Use | +|---|---| +| **Schedule** | "Workflow," "job stream" | +| **Job** | "Task," "process," "step" | +| **Agent** | "LSAM" (in user-facing text), "server," "host" | +| **Frequency** | "Trigger," "schedule pattern," "recurrence rule" | +| **Threshold** | "Counter," "flag" (without context) | +| **Solution Manager** | "Web UI," "portal," "web console" | +| **Event** | "Trigger," "action" (as OpCon-specific terms) | +| **Customer** | "Client" — always use "customer" | diff --git a/.claude/skills/technical-writer/resources/opcon-golden-examples.md b/.claude/skills/technical-writer/resources/opcon-golden-examples.md new file mode 100644 index 0000000..474afae --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-golden-examples.md @@ -0,0 +1,192 @@ +# Golden Examples + +Complete, fully-compliant reference examples for each documentation type. +Use these to calibrate output quality. Every element in these examples — +front matter, structure, tone, formatting, and cross-references — follows +the standards in opcon-documentation-standards.md and is appropriate for the +target audience per opcon-learner-roles.md. + +> **How to use this file:** When writing or reviewing a page, find the +> golden example that matches the documentation type and audience +> complexity. Use it as a quality benchmark — the finished page should +> be structurally and stylistically comparable. + +--- + +## Conceptual Example + +Target audience: Automation Engineer (moderate-to-high technical background) + +```markdown +--- +title: How job dependencies work +description: "Understand how job dependencies control execution order within and across schedules so jobs run in the correct sequence." +tags: + - Conceptual + - Automation Engineer + - Jobs + - Schedules +--- +# How job dependencies work + +Job dependencies control the order in which jobs run. When a job has a +dependency configured, it will not start until the job it depends on +has reached the required status. Dependencies let you build reliable +processing sequences without relying on fixed start times. + +## Why dependencies matter + +Timed starts are fragile — if an upstream job runs long or fails, a +downstream job that starts on a fixed schedule may process incomplete +or missing data. Dependencies let the downstream job wait for the +correct signal instead of a clock, making the automation resilient to +variable run times. + +## Dependency types + +OpCon supports three dependency types, each designed for a different +relationship between jobs: + +| Type | When to use | What it does | +|---|---|---| +| Requires | The downstream job needs the upstream job to succeed | Holds the downstream job until the upstream job finishes with the required exit code | +| After | The downstream job should run after the upstream job regardless of outcome | Releases the downstream job once the upstream job reaches a finished status, whether it succeeded or failed | +| Excludes | The downstream job should not run if the upstream job reaches a certain status | Removes the downstream job from the schedule if the upstream job matches the specified condition | + +## How dependencies resolve + +OpCon evaluates each job's dependencies at every check interval. When +all dependencies for a job are satisfied, the job is released to run. +If a dependency is not met by the time the schedule closes, the job +remains in a **Waiting** status and is reported as unresolved for +that day. + +## Cross-schedule dependencies + +Dependencies can span schedules. A job in one schedule can require a +job in a different schedule to complete before it starts. When +configuring a cross-schedule dependency, specify both the schedule +name and the job name. OpCon resolves the dependency regardless of +which schedule builds first. + +**Related topics:** + +- [Add a dependency to a job](add-job-dependency.md) +- [How frequencies work](how-frequencies-work.md) +- [Respond to a job in Waiting status](respond-waiting-job.md) +``` + +--- + +## Procedural Example + +Target audience: Automation Engineer (technical, task-focused) + +```markdown +--- +title: Add a frequency to a job +description: "Add a frequency to a job to define when OpCon will build and submit the job for execution." +tags: + - Procedural + - Automation Engineer + - Frequencies + - Jobs +--- +# Add a frequency to a job + +Add a frequency to a job to specify when OpCon should build and run +it. A job without a frequency will not be built into the daily +schedule. + +!!! note "Prerequisite" + The job must exist in the Job Master before a frequency can be + added. See [Add a job to a schedule](add-job.md). + +To add a frequency, complete the following steps: + +1. Go to the **Administration** menu and select **Job Master**. +2. In the **Schedule** list, select the schedule. +3. Select the job. The Job Master Details page is displayed. +4. Select the **Frequency** tab. +5. Select the **Add** button. The Add Frequency dialog is displayed. +6. In the **Frequency Name** field, select an existing frequency from + the list or enter a name to create a new one. +7. Configure the frequency options. +8. Select the **Save** button. The frequency is added to the job. + +!!! tip + Select the **Forecast** button to preview which dates the + frequency will generate before saving. This is especially useful + when holiday calendar offsets are involved. + +**Related topics:** + +- [How frequencies work](how-frequencies-work.md) +- [Configure a holiday calendar](configure-holiday-calendar.md) +- [Add a dependency to a job](add-job-dependency.md) +``` + +--- + +## Reference Example + +Target audience: Compliance Team and Operations Staff (scanning for specific information) + +```markdown +--- +title: Standard reports +description: "Pre-configured reports available in OpCon, organized by category with format options and descriptions." +tags: + - Reference + - Compliance Team + - Operations Staff + - Reports +--- +# Standard reports + +The Standard Reports section provides pre-configured reports related +to jobs, schedules, agents, and system activity. Reports are available +in PDF and/or Excel formats. + +## Job reports + +| Report | Description | Formats | +|---|---|---| +| Job Execution History | All job runs within a selected date range, including start time, end time, duration, exit code, and agent. | PDF, Excel | +| Failed Jobs | All jobs that ended in a failed status within the selected period, with exit codes and job details. | PDF, Excel | +| Job Execution List | A detailed list of all job executions for a specified schedule and date range. | Excel | + +## Schedule reports + +| Report | Description | Formats | +|---|---|---| +| Schedule Build Summary | A record of all schedule builds for a selected date range, including build status and job counts. | PDF, Excel | +| Unbuilt Jobs | All jobs that were not built into the daily schedule for a selected date, with the reason each job was excluded. | PDF, Excel | + +## Agent reports + +| Report | Description | Formats | +|---|---|---| +| Machine Status | Current communication status for all defined agents, including last contact time and machine group membership. | PDF, Excel | + +**Related topics:** + +- [Generate a report](generate-report.md) +- [Export report data](export-report.md) +``` + +--- + +## Why These Examples Matter for AI Workflows + +Golden examples serve as implicit calibration for AI output. When the +AI has seen a complete, compliant example of each documentation type, +it can pattern-match against the example rather than assembling output +purely from rules. This produces higher-quality first drafts because: + +- Structure is internalized, not just described +- Tone is demonstrated, not just specified +- Cross-reference patterns are shown in context +- Front matter is modeled with realistic tags +- The relationship between conceptual brevity and procedural precision + is visible in the contrast between examples diff --git a/.claude/skills/technical-writer/resources/opcon-learner-roles.md b/.claude/skills/technical-writer/resources/opcon-learner-roles.md new file mode 100644 index 0000000..be06aa7 --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-learner-roles.md @@ -0,0 +1,211 @@ +# Learner Role Guidelines + +Guidelines for understanding the roles within OpCon. Use these guidelines to produce accurate, audience-appropriate documentation for each role. + +## Section Reference + +| Section | Purpose | +|---------|---------| +| Who they are | Understand the audience and correctly describe the role in documentation | +| Why they matter | Frame content around business value | +| Knowledge domains | Identify relevant topics — conceptual and durable, not tied to nav structure | +| Key terminology | Focus vocabulary when writing for this audience | +| This role does NOT | Prevent including out-of-scope content | +| Common overlap | Handle edge cases where roles share responsibilities | +| Tone adjustment | Calibrate writing style per audience | +| Assume they understand | Prevent over-explaining known concepts and under-explaining unfamiliar ones | + +## Decision Framework + +When writing documentation, identify the primary audience by role. Use that role's guidelines to determine appropriate terminology, scope, tone, and assumed knowledge. If a page serves multiple roles, use the least technical audience's tone while respecting the knowledge boundaries of all roles involved. + +--- + +## 1. System Administrator + +**Who they are:** Infrastructure staff responsible for installing, configuring, and maintaining the OpCon environment — servers, databases, agents, licensing, user accounts, and system-wide settings. In smaller organizations, the System Administrator and Automation Engineer roles are often held by the same person. + +**Why they matter:** They keep OpCon running. Without proper installation, configuration, and maintenance, automation stops. They are the foundation everything else depends on. + +**Knowledge domains:** +- Installing, upgrading, and patching OpCon and its components +- Hardware, software, and network requirements +- Agent and machine setup, communication configuration, and troubleshooting +- Database administration and connection configuration (SQL Server) +- User account and role management within OpCon +- Licensing and activation +- Backup, restore, and disaster recovery +- SSL certificates and security configuration +- Log management and diagnostics +- SMTP and notification configuration +- Global properties and system-wide settings + +**Key terminology:** machine, agent, SAM (Schedule Activity Monitor), OpCon database, role, user account, license, diagnostic log, global property, batch user, machine group, communication settings + +**This role does NOT:** +- Build or maintain job schedules (that is the Automation Engineer's responsibility) +- Monitor the daily schedule in real time (that is the Operations Staff's responsibility) +- Define what processes should be automated (that is the Application Owner's responsibility) +- Approve or document business automation requirements + +**Common overlap:** In smaller organizations, System Administrators and Automation Engineers are often the same person. Documentation written for System Administrators should focus on infrastructure and system configuration, not job design or daily operations. + +**Tone adjustment:** Highly technical audience. Comfortable with servers, databases, Windows services, certificates, and networking. Prioritize precision, exact steps, and technical accuracy. They appreciate concise instructions without excessive explanation of concepts they already understand. + +**Assume they understand:** Windows Server administration, SQL Server, IIS, Active Directory, SSL certificates, DNS, SMTP configuration, Windows Services, and general networking concepts. + +--- + +## 2. Automation Engineer + +**Who they are:** The people who build and maintain job schedules — the job definitions, frequencies, dependencies, events, and thresholds that make up the automation workflows. They translate business requirements into configured automation and are responsible for the reliability and correctness of what OpCon executes. + +**Why they matter:** They are the builders. Without well-designed jobs and schedules, automation either fails or doesn't exist. The quality of their work directly determines whether automated processes are reliable, auditable, and maintainable. + +**Knowledge domains:** +- Creating and configuring schedules and jobs in the Job Master and Schedule Master +- Configuring job properties (job type, command line, agent, batch user, documentation) +- Defining frequencies and integrating holiday calendars +- Setting up job dependencies (requires, after, excludes) within and across schedules +- Creating and using thresholds and resources for dependency and flow control +- Configuring OpCon events (actions triggered by job statuses) +- Building and managing sub-schedules and container jobs +- Testing and validating job build behavior +- Reading job output and logs to debug failures +- Using tags and groups to organize jobs at scale +- Managing cross-schedule dependencies +- Working with the OpCon API for integrations and automation-of-automation + +**Key terminology:** job, schedule, frequency, dependency, threshold, resource, event, sub-schedule, container job, job type, batch user, agent, exit code, restart, skip, job master, schedule master, holiday calendar, multi-instance + +**This role does NOT:** +- Install or configure OpCon infrastructure (that is the System Administrator's responsibility) +- Monitor the daily schedule in real time during operations (that is the Operations Staff's responsibility) +- Define the business requirements for what to automate (that is the Application Owner's responsibility) + +**Common overlap:** In smaller organizations, Automation Engineers also perform Operations Staff duties. Documentation written for Automation Engineers should focus on designing and configuring automation, not on real-time monitoring or infrastructure management. + +**Tone adjustment:** Technical audience comfortable with scripting, command lines, and system concepts. They want precise, accurate instructions with clear explanations of how configuration choices affect behavior. They appreciate documentation that explains the reasoning behind design decisions — not just the steps. + +**Assume they understand:** Basic scripting or command-line concepts, how job scheduling generally works, and intermediate-level Windows or Linux system administration. Do not assume they understand SQL Server database administration or infrastructure-level OpCon configuration. + +--- + +## 3. Operations Staff + +**Who they are:** The people responsible for monitoring and managing the daily schedule — watching jobs run, responding to failures, placing jobs or schedules on hold, and ensuring the day's automation completes successfully. They are OpCon's front line during live processing. + +**Why they matter:** When something goes wrong, they respond. Without attentive operations coverage, failed jobs go undetected, processing deadlines are missed, and downstream business processes are impacted. + +**Knowledge domains:** +- Monitoring jobs and schedules in real time using the Operations view and Solution Manager +- Understanding all job statuses and what each status requires in response +- Responding to job failures (restart, skip, mark as Failed-OK, cancel) +- Placing jobs and schedules on hold and releasing them +- Forcing jobs to run or be skipped outside their normal frequency +- Reading job output and OpCon logs to diagnose failures +- Subscribing to and managing notifications and alerts +- Escalating unresolved issues to Automation Engineers or System Administrators +- Using the daily schedule and history views to track completion + +**Key terminology:** job status, failed, on hold, restart, skip, cancel, force run, daily schedule, operations view, job output, frequency override, schedule build, notifications + +**This role does NOT:** +- Build or modify job definitions in the Job Master (that is the Automation Engineer's responsibility) +- Configure agents, machines, or system settings (that is the System Administrator's responsibility) +- Define business automation requirements (that is the Application Owner's responsibility) + +**Common overlap:** In smaller organizations, Operations Staff members may also function as Automation Engineers. Documentation written for Operations Staff should focus exclusively on real-time monitoring and response — not on how jobs are designed or how infrastructure is maintained. + +**Tone adjustment:** Task-oriented, time-pressured audience. They are often responding to an active problem. Instructions must be fast to scan and clearly stated, focused on the specific action required. Avoid lengthy explanations — they need to know what to do right now, not the design philosophy behind it. + +**Assume they understand:** What automation is and why it matters, basic OpCon navigation, how to read a job status list, and who to escalate to when they cannot resolve an issue. Do not assume they understand job configuration, frequency design, or infrastructure-level troubleshooting. + +--- + +## 4. Application Owner + +**Who they are:** The business-side owners of the processes being automated. They know what the automation is supposed to accomplish, can define requirements, validate results, and escalate when an automated process fails to deliver the expected outcome. They typically do not configure OpCon directly. + +**Why they matter:** They define what "success" looks like for a given automation workflow. Their requirements drive what Automation Engineers build, and their confirmation validates that automation behaves correctly. Without clear ownership, automation becomes unaccountable. + +**Knowledge domains:** +- Understanding which schedules and jobs support their business process +- Reading job execution history reports to confirm automated results +- Communicating failures, changes, and requirements to the Automation Engineering team +- Understanding the business impact when a job fails or runs outside its expected window +- Reviewing and approving automation changes that affect their processes + +**Key terminology:** schedule, job, job status, execution history, report, job output, frequency + +**This role does NOT:** +- Configure jobs, schedules, or frequencies in OpCon +- Install or maintain OpCon infrastructure +- Monitor the daily schedule in real time +- Resolve technical job failures directly + +**Common overlap:** Application Owners may work closely with Automation Engineers when validating requirements or reviewing proposed changes. Documentation written for Application Owners should focus on understanding outcomes and communicating requirements — not on configuring the system. + +**Tone adjustment:** Business-focused, non-technical audience. Avoid OpCon-specific jargon. Focus on outcomes and business impact rather than system mechanics. Use plain language and concrete examples from their business domain. + +**Assume they understand:** Their own business processes and the expected result of the automation they own. Do not assume they understand OpCon configuration, job types, frequency design, or technical failure diagnostics. + +--- + +## 5. Business Analyst + +**Who they are:** The people who document automation requirements, map business processes to OpCon workflows, and bridge communication between Application Owners and Automation Engineers. They typically do not configure OpCon directly, but need a deep enough understanding of how OpCon works to write accurate and buildable specifications. + +**Why they matter:** Clear, accurate requirements prevent rework. Business Analysts translate what the business needs into documentation that Automation Engineers can implement correctly the first time, reducing miscommunication and configuration errors. + +**Knowledge domains:** +- Understanding the OpCon job and schedule model well enough to write accurate requirements +- Reading and interpreting job execution history and reports +- Documenting process dependencies, timing requirements, and exception handling +- Mapping business processes to OpCon concepts (schedules, jobs, frequencies, dependencies, thresholds) +- Reviewing proposed automation designs for accuracy and completeness relative to requirements + +**Key terminology:** schedule, job, frequency, dependency, threshold, event, job type, execution history, sub-schedule + +**This role does NOT:** +- Configure jobs or schedules in OpCon +- Monitor daily operations +- Resolve technical job failures +- Make infrastructure decisions + +**Common overlap:** Business Analysts often work closely with both Application Owners (gathering requirements) and Automation Engineers (validating designs). Documentation for Business Analysts should provide enough conceptual depth to write accurate specifications without diving into step-by-step configuration procedures. + +**Tone adjustment:** Analytical and process-oriented audience. Comfortable with structured thinking and documentation but may not be deeply technical. Explain how OpCon concepts map to process concepts they already understand (e.g., "a frequency in OpCon is analogous to a recurrence rule for a calendar event"). Documentation should be thorough and precise. + +**Assume they understand:** Business process mapping, requirements documentation, workflow concepts, and a general understanding of what automation is and why it exists. Do not assume deep technical knowledge of OpCon configuration, job types, or scripting. + +--- + +## 6. Compliance Team + +**Who they are:** Auditors, compliance officers, examiners, or information security staff who need visibility into OpCon's job execution history, audit logs, and reports to verify that automated processes are operating as documented and within regulatory requirements. They do not configure OpCon. + +**Why they matter:** In regulated financial institutions, automated job processing must be demonstrably reliable, controlled, and auditable. The Compliance Team verifies that automation is operating within documented controls and can produce evidence for internal and external auditors. + +**Knowledge domains:** +- Reading and exporting job execution history reports for specified time periods +- Understanding job audit logs and what they prove from a controls perspective +- Generating and downloading schedule activity reports +- Interpreting job statuses, failure codes, and manual overrides +- Understanding what controls exist around who can modify automation (role-based access in OpCon) +- Reviewing user access and role assignments within OpCon +- Generating and presenting audit artifacts to internal or external reviewers + +**Key terminology:** job execution history, audit log, report, schedule activity, job status, exit code, role, user access, manual override, schedule build + +**This role does NOT:** +- Configure jobs, schedules, or system settings +- Monitor the daily schedule in real time +- Resolve job failures +- Approve or design automation workflows + +**Common overlap:** Compliance Team members may also be Application Owners in some organizations. Documentation written for the Compliance Team should connect reports and logs directly to regulatory controls — not explain how the automation was built or how OpCon is configured internally. + +**Tone adjustment:** Evidence-focused audience. They care about what the system can prove, not how it works. Connect every report or log to what it demonstrates from a compliance standpoint. Use plain language and avoid internal OpCon jargon. Precision matters — document exactly what each report contains and what it does and does not show. + +**Assume they understand:** The regulatory landscape for financial institutions (FFIEC, FDICIA, NCUA, SOX), what an audit trail is and why it matters, and the general concepts of operational risk and control frameworks. Do not assume they understand OpCon configuration, job type specifics, or automation design principles. diff --git a/.claude/skills/technical-writer/resources/opcon-primary-analysis.md b/.claude/skills/technical-writer/resources/opcon-primary-analysis.md new file mode 100644 index 0000000..f8a6c29 --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-primary-analysis.md @@ -0,0 +1,195 @@ +# Writer-Friendly Documentation Standard + +> **Purpose:** This file defines the primary page template used to evaluate documentation completeness and structure. Every feature page submitted for review is scored against these 11 active sections (0–1, 4–12). Sections 2 and 3 are deprecated — their content is now part of Section 1. +> +> **Used by:** `doc-quality-assessor` — Template Adherence Review (Step 3) and Completeness subscore. + +--- + +## Template Overview + +Every feature page must include all 11 active sections below, in order. Each section has a defined intent — use it to judge whether the content present actually fulfills the section's purpose, not just whether a heading exists. + +| # | Section Title | One-Line Intent | +|---|---|---| +| 0 | Theme and Audience | Declares page type and target reader at the top | +| 1 | What Is It? (Overview, Use Cases, and Value) | Prose description + bullet list of scenarios and benefits | +| ~~2~~ | ~~When Would You Use It?~~ | **Deprecated** — merge content into § 1 | +| ~~3~~ | ~~Why Would You Use It?~~ | **Deprecated** — merge content into § 1 | +| 4 | How To Implement It | Prerequisites, numbered steps, one example | +| 5 | Configuration Options | Table: Setting \| What It Does \| Default \| Notes | +| 6 | Exception Handling | Error → Meaning → Fix | +| 7 | Administration | Enable/disable, roles, maintenance | +| 8 | Security Considerations | Auth, authorization, data security, sensitive data | +| 9 | Operations (Running in Production) | Monitoring, alerts, performance/scaling | +| 10 | FAQs | Most predictable user questions | +| 11 | Examples / Recipes | Real-world scenarios | +| 12 | Glossary | Short definitions of key terms | + +--- + +## Section Definitions + +### Section 0 — Theme and Audience + +At the top of the page, clearly state: + +- **Theme:** one of *Build*, *Configure*, *Troubleshoot*, or *Overview* +- **Who Is It For?** — the intended audience, selected from: + - *System Administrator* + - *Automation Engineer* + - *Application Owner* + - *Operations Staff* + - *Business Analyst* + - *Compliance Team* + +**Evaluation pass criteria:** Both fields are present, populated with a valid value from the allowed lists, and placed at the top of the page before any body content. + +--- + +### Section 1 — What Is It? (Overview, Use Cases, and Value) + +A combined section that explains what the feature is, when readers would use it, and why it provides value. Structure it as: + +1. **Prose description** (1–3 sentences): what this feature does and what problem it solves. Written for a first-time reader. +2. **Bullet list** (at least 2 bullets): key use-case scenarios and/or benefits. Phrased from the reader's perspective — either as scenarios ("Use this when...", "You are configuring...") or as outcomes ("Reduces...", "Ensures..."). Do not include bullets that simply restate the prose description. + +Do not use subheadings inside this section. Do not create separate `## When would you use it?` or `## Why would you use it?` headings — those are deprecated. + +**Evaluation pass criteria:** Prose description present (1–3 sentences). At least 2 bullets present. No deprecated When/Why subheadings. No redundancy between prose and bullets. + +--- + +### Section 2 — ~~When Would You Use It?~~ (DEPRECATED) + +> **This section is deprecated.** Do not create a `## When would you use it?` heading on any new or revised page. Merge existing When content into the bullet list under § 1 (What Is It?) and remove the heading. +> +> When reviewing existing pages: flag any `## When would you use it?` section as a violation and suggest merging its bullets into § 1. + +--- + +### Section 3 — ~~Why Would You Use It?~~ (DEPRECATED) + +> **This section is deprecated.** Do not create a `## Why would you use it?` heading on any new or revised page. Merge existing Why content into the bullet list under § 1 (What Is It?) and remove the heading. +> +> When reviewing existing pages: flag any `## Why would you use it?` section as a violation and suggest merging its bullets into § 1. + +--- + +### Section 4 — How To Implement It + +Three required parts: + +1. **Prerequisites** — what must be true or in place before starting +2. **Numbered steps** — one action per step, in order +3. **One short example or screenshot** — a concrete illustration of the completed setup or a key step + +**Evaluation pass criteria:** All three parts present. Steps are numbered. At least one example or screenshot placeholder/description present. + +--- + +### Section 5 — Configuration Options + +A table with four columns: + +| Setting | What It Does | Default | Notes | +|---|---|---|---| + +Each configurable setting for the feature should appear as one row. + +**Evaluation pass criteria:** Table present with all four columns. At least one row populated. No placeholders left blank without a stated reason. + +--- + +### Section 6 — Exception Handling + +A list of common problems and solutions. Each entry follows this pattern: + +> **Error or symptom** → What it means → How to fix it + +**Evaluation pass criteria:** At least 2 error/symptom entries present. Each entry includes the error, its meaning, and a fix. Not a generic "contact support" placeholder. + +--- + +### Section 7 — Administration + +How administrators manage the feature on an ongoing basis. Must cover: + +- How to enable or disable the feature +- Which roles can access or configure it +- Routine maintenance tasks (if any) + +**Evaluation pass criteria:** All three sub-topics addressed. Role names use product terminology (not code names). + +--- + +### Section 8 — Security Considerations + +Covers the security surface of the feature: + +- Authentication — what credentials or tokens are involved +- Authorization — who can access or modify this feature +- Data security — what data is stored, transmitted, or exposed +- Sensitive data — any PII, credentials, or regulated data handled + +**Evaluation pass criteria:** All four sub-topics addressed, even if briefly. Section is not omitted or left as a stub. + +--- + +### Section 9 — Operations (Running in Production) + +How the feature behaves and is monitored in a live environment: + +- Monitoring — what signals indicate the feature is healthy +- Alerts — what conditions should trigger notification +- Performance and scaling — known limits, load considerations, or tuning guidance + +**Evaluation pass criteria:** All three sub-topics addressed. Specific metrics, alert conditions, or thresholds stated where applicable. + +--- + +### Section 10 — FAQs + +A list of the most predictable questions a user would have after reading the page. Each FAQ is a question-and-answer pair. + +**Evaluation pass criteria:** At least 3 Q&A pairs present. Questions reflect real user confusion or edge cases, not rephrased section headings. + +--- + +### Section 11 — Examples / Recipes + +Real-world scenarios showing the feature in use end-to-end. Each example should include: + +- The scenario or goal +- The configuration or steps used +- The expected outcome + +**Evaluation pass criteria:** At least 1 complete example present. Must be specific to a plausible real-world situation, not generic. + +--- + +### Section 12 — Glossary + +Short definitions of key terms introduced or heavily used on the page. Format: + +> **Term** — definition in one or two sentences. + +**Evaluation pass criteria:** At least 2 terms defined. Terms are specific to the feature or domain, not general IT vocabulary. + +--- + +## Scoring Guidance + +When evaluating a page against this template, apply the following status to each section: + +| Status | Meaning | +|---|---| +| ✅ Present and complete | Section exists and fulfills its stated intent | +| ⚠️ Present but incomplete | Section exists but is missing one or more required elements | +| ❌ Missing | Section is absent or reduced to a heading with no content | + +The **Completeness subscore** (weighted 25%) is derived from the ratio of ✅ sections to the 11 active sections (0–1, 4–12). Sections 2 and 3 are excluded from scoring — their presence is a violation, not a credit. + +The **Structure / Template Adherence subscore** (weighted 15%) evaluates whether sections appear in order, use the correct format (table, numbered list, etc.), and meet the structural requirements stated above — not just whether content is present. + +**Violation: deprecated headings present.** If a page contains `## When would you use it?` or `## Why would you use it?` as standalone headings, flag each as a structure violation and recommend merging the content into § 1. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0190e94..8d7a8c1 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -11,6 +11,6 @@ jobs: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: - node-version: '14' + node-version: '20' - run: yarn install - run: yarn build diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 0af435e..1d90f80 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -11,7 +11,7 @@ jobs: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: - node-version: '14' + node-version: '20' - uses: kheiakiyama/install-azcopy-action@v1 with: version: 'v10' diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4f7adf7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,70 @@ +# Java Agent Documentation — Claude Code Project + +This repository contains the Java Agent product documentation site built with Docusaurus. + +## Technical Writer Skill + +A technical writer skill and its resource files are bundled in this repository at `.claude/skills/technical-writer/`. The skill enforces OpCon documentation standards for terminology, voice, structure, and formatting. + +### Skill Location + +``` +.claude/skills/technical-writer/ +├── SKILL.md # Skill definition and operating modes +└── resources/ + ├── opcon-documentation-standards.md # Action verbs, UI terms, formatting rules, pre-flight checklist + ├── opcon-documentation-types.md # Conceptual / Procedural / Reference templates + ├── opcon-glossary.md # Controlled vocabulary — customer-facing terms and banned terms + ├── opcon-learner-roles.md # Audience profiles and tone guidance per role + ├── opcon-golden-examples.md # Reference examples for each documentation type + ├── opcon-api-reference.md # API endpoint documentation templates + └── opcon-primary-analysis.md # 13-section template for page completeness scoring +``` + +### Using the Skill + +Invoke the skill when writing, reviewing, or editing documentation pages. The skill operates in four modes: + +| Mode | Trigger words | Behavior | +|---|---|---| +| **Write** | "Write," "Create," "Draft" | Produce complete documentation matching the page type template | +| **Review** | "Review," "Check," "Audit" | Report violations with line references and suggested fixes | +| **Edit** | "Fix," "Update," "Revise" | Apply targeted changes while preserving compliant content | +| **Consult** | "Should I," "How do I" | Provide guidance from the standards without producing output | + +### Automatic invocation on document changes + +Apply the technical-writer skill automatically whenever you work on `.md` files in `docs/`: + +| Situation | Mode | Required action | +|---|---|---| +| You edit an existing `.md` file in `docs/` | Edit | Run the skill before reporting the task complete — fix all violations found | +| You create a new `.md` file in `docs/` | Write | Produce a compliant page from the start using the correct page type template | +| User asks you to review or audit docs | Review | Report all violations with file path, line number, and suggested fix | +| User asks "should I" or "how do I" about standards | Consult | Answer from the standards without producing output | + +Do not report a documentation task as complete until the skill has run and all violations are resolved. + +### Key Standards + +- **Terminology**: Use customer-facing terms. Never use: LSAM, execute/executed/executing, right-select, click, drop-down, checkbox, navigate to, launch, client, task/process (as job synonyms) +- **Voice**: Second person ("you") for instructions. No first person ("we," "our"). Present tense for descriptions, imperative for steps. +- **Structure**: Numbered steps for procedures, one action per step. Lead-in sentence required: "To [goal], complete the following steps:" +- **Front matter**: Every page requires `title:`, `description:`, and `tags:` (Type + Role + Feature area) + +## Repository Structure + +``` +docs/ # Primary documentation pages +src/ # Docusaurus theme customizations +static/ # Images and static assets +sidebars.js # Navigation structure +docusaurus.config.js # Site configuration +``` + +## Running Locally + +```bash +yarn install +yarn start +``` diff --git a/docs/administration/configuration-file.md b/docs/administration/configuration-file.md index 5b891df..1245aa2 100644 --- a/docs/administration/configuration-file.md +++ b/docs/administration/configuration-file.md @@ -1,60 +1,77 @@ +--- +sidebar_label: 'Configuration file' +title: Java Agent configuration file +description: "Reference for all settings in the Agent.config file, including network, job limits, debug options, JORS, and library configuration." +tags: + - Reference + - System Administrator + - Agents +--- + # Agent.config file configuration -The Agent.config is the Java Agent configuration file name. The configuration of the Java Agent requires setting the required properties in the Agent.config file located in the \\Java Agent \[CPU\]\\ directory. +## What is it? + +The `Agent.config` file is the Java Agent configuration file. It controls how the agent communicates with OpCon, how many jobs it runs concurrently, where it finds Java libraries, and how it captures job output. + +- Use this reference when setting up the agent for the first time to configure the required network and job settings +- Use this reference when troubleshooting connectivity or job output issues to verify that settings match the values defined in OpCon + +The configuration of the Java Agent requires setting the required properties in the `Agent.config` file located in the `\Java Agent [CPU]\` directory. :::note The Configuration Directory is based on where you installed your programs. For more information, refer to [File Locations](https://help.smatechnologies.com/opcon/core/file-locations) in the **Concepts** online help. ::: -The following settings are critical to the operation of the Agent with OpCon: +The following settings are critical to the operation of the agent with OpCon: -- **MaximumNumberOfJobs**: This value determines the maximum number of jobs the Agent is allowed to process concurrently. -- **SocketNumberToSAM**: This value is used for communication between the Agent and the SMANetCom; consequently, the value for this setting and the value for the Socket Number on the Machines screen in the Enterprise Manager (EM) must match. -- **JORSSocket**: This value is used for communicating job output information with the Enterprise Manager (EM). +- **MaximumNumberOfJobs**: Determines the maximum number of jobs the agent is allowed to process concurrently +- **SocketNumberToSAM**: Used for communication between the agent and SMANetCom; this value must match the socket number on the Machines screen in the Enterprise Manager +- **JORSSocket**: Used for communicating job output information with the Enterprise Manager ## General settings The table contains the basic settings for the Java Agent. -|[General Settings]|Default|Description| +| [General Settings] | Default | Description | |--- |--- |--- | -|MaximumNumberOfJobs|50|Defines the maximum number of jobs the Agent can simultaneously manage. When setting the MaximumNumberOfJobs, consider the Agent machine's processor speed and memory (RAM) size. No job is processed when this setting is 0.| +| MaximumNumberOfJobs | 50 | Defines the maximum number of jobs the agent can simultaneously manage. When setting the MaximumNumberOfJobs, consider the agent machine's processor speed and memory (RAM) size. No job is processed when this setting is 0. | ## TCP/IP parameters The table contains the network settings for the Java Agent. -|[TCP/IP Parameters]|Default|Description| +| [TCP/IP Parameters] | Default | Description | |--- |--- |--- | -|SocketNumberToSAM|17100|Defines the socket number through which the Agent and the SMANetCom communicate. This number must match the Machine's socket number defined in the Enterprise Manager. If there are multiple Agents installed on one machine, each Agent must have a unique value. For an up-to-date list of unused ports, please refer to the Internet Assigned Numbers Authority at www.iana.org.| -|AllowedIPAddress_1|ANY|Determines if communication from the SMANetCom to the Agent is restricted to one or more TCP/IP addresses. If ANY is specified, the Agent accepts communication from any TCP/IP address. If a specific TCP/IP address is defined (e.g., 126.40.90.231), the Agent only accepts communication from the specified address. The Agent refuses a connection if communication is attempted from another address. This definition enhances communication security by refusing communications from other TCP/IP addresses. If multiple SAMs are on a network, this address ensures the Agent is only accepting messages from the intended SMANetCom. This parameter is case-sensitive.| -|AllowedIPAddress_2|Blank|Same as Address_1 explanation.| -|AllowedIPAddress_3|Blank|Same as Address_1 explanation.| -|AllowedIPAddress_4|Blank|Same as Address_1 explanation.| -|AllowedIPAddress_5|Blank|Same as Address_1 explanation.| +| SocketNumberToSAM | 17100 | Defines the socket number through which the agent and SMANetCom communicate. This number must match the machine's socket number defined in the Enterprise Manager. If there are multiple agents installed on one machine, each agent must have a unique value. For an up-to-date list of unused ports, refer to the Internet Assigned Numbers Authority at www.iana.org. | +| AllowedIPAddress_1 | ANY | Determines if communication from SMANetCom to the agent is restricted to one or more TCP/IP addresses. If ANY is specified, the agent accepts communication from any TCP/IP address. If a specific TCP/IP address is defined (for example, `126.40.90.231`), the agent only accepts communication from the specified address. The agent refuses a connection if communication is attempted from another address. This definition enhances communication security by refusing communications from other TCP/IP addresses. If multiple SAMs are on a network, this address ensures the agent only accepts messages from the intended SMANetCom. This parameter is case-sensitive. | +| AllowedIPAddress_2 | Blank | Same as AllowedIPAddress_1. | +| AllowedIPAddress_3 | Blank | Same as AllowedIPAddress_1. | +| AllowedIPAddress_4 | Blank | Same as AllowedIPAddress_1. | +| AllowedIPAddress_5 | Blank | Same as AllowedIPAddress_1. | ## Process creation parameters -The table contains the process settings involved in the execution of Java Agent jobs. +The table contains the process settings involved in running Java Agent jobs. -|[Process Creation Parameters]|Default|Description| +| [Process Creation Parameters] | Default | Description | |--- |--- |--- | -|CaptureJobOutput|TRUE|Enables/Disables the creation of job output files for each OpCon job. If set to TRUE, the Agent saves the output from each started job in a subdirectory (under the Agent directory) called JobOutput. The Agent saves each job's output to unique files named with the following syntax:"*OpConxps job name up to 12 chars*_*unique number*.TXT" View Job Output feature works only if this setting is TRUE.| +| CaptureJobOutput | TRUE | Enables or disables the creation of job output files for each OpCon job. If set to `TRUE`, the agent saves the output from each started job in a subdirectory (under the agent directory) called `JobOutput`. The agent saves each job's output to unique files named with the syntax: `_.TXT`. The View Job Output feature works only if this setting is `TRUE`. | ## Debug options The table contains the log and trace settings for troubleshooting the Java Agent. -|[Debug Options]|Default|Description| +| [Debug Options] | Default | Description | |--- |--- |--- | -|ConnectorDebug|OFF|Enables debug tracing in the Agent.| +| ConnectorDebug | OFF | Enables debug tracing in the agent. | :::note This trace is helpful for troubleshooting and debugging. -If ON, the Agent enables debug tracing. +If `ON`, the agent enables debug tracing. -If OFF, the Agent disables debug tracing. +If `OFF`, the agent disables debug tracing. ::: :::danger @@ -65,26 +82,26 @@ Do not turn this option on unless directed by SMA. The table contains settings for configuring JORS for job output retrieval. -|[JORS Settings]|Default|Description| +| [JORS Settings] | Default | Description | |--- |--- |--- | -|JORSSocket|18110|Defines the socket number through which the JORS Service and the Agent communicate. The Job Output Retrieval System (JORS) uses this socket. This number must match the JORS Port Number defined in the Enterprise Manager under the Advanced Machine Settings in the Communication Settings category. If there are multiple Agents installed on one machine, each Agent's JORS Service must have a unique port. For an up-to-date list of unused ports, please refer to the Internet Assigned Numbers Authority at www.iana.org.| +| JORSSocket | 18110 | Defines the socket number through which the JORS service and the agent communicate. The Job Output Retrieval System (JORS) uses this socket. This number must match the JORS Port Number defined in the Enterprise Manager under the Advanced Machine Settings in the Communication Settings category. If there are multiple agents installed on one machine, each agent's JORS service must have a unique port. For an up-to-date list of unused ports, refer to the Internet Assigned Numbers Authority at www.iana.org. | :::note -The JORSSocket number needs to be set in both the Agent.config and the advanced machine setting in the EM. For more information on modifying the JORS port number, refer to Set JORS Port Number for the Machine in the Enterprise Manager online help. +The JORSSocket number needs to be set in both the `Agent.config` and the advanced machine setting in the Enterprise Manager. For more information on modifying the JORS port number, refer to Set JORS Port Number for the Machine in the Enterprise Manager online help. ::: ## Application connector settings This table contains the application connector settings for the Java Agent. -|[Application Connector Settings]|Default|Description| +| [Application Connector Settings] | Default | Description | |--- |--- |--- | -|ConnectorName|Java Agent|The name of the agent. This value does not need to be changed.| -|LibrariesInFile|N|This defines if the information about the libraries that need to be loaded into the Java Agent class path are defined in a file or available in the libraries directory.Values: Y or N.| -|LibrariesFileName|Blank|Defines the full path and name of the file that contains the information about the libraries that need to be loaded into the Java Agent class path. Required if LibrariesInFile configuration is set to Y.| -|LibrariesDirectory|Libraries|The name of the directory where the libraries that need to be loaded into the Java Agent class path are located. Only enter the directory name as this will be appended to the root installation directory. Required if LibrariesInFile configuration is set to N.| -|JobStatusCheckInterval|5|The time in seconds to wait between status checks to determine if a job has completed processing.| -|JobStatusCheckInitialPollDelay|5|The time in seconds to wait before the initial status check to determine if a job has completed processing.| +| ConnectorName | Java Agent | The name of the agent. This value does not need to be changed. | +| LibrariesInFile | N | Defines if the information about the libraries to be loaded into the Java Agent class path is defined in a file or available in the libraries directory. Values: `Y` or `N`. | +| LibrariesFileName | Blank | Defines the full path and name of the file that contains the information about the libraries to be loaded into the Java Agent class path. Required if `LibrariesInFile` is set to `Y`. | +| LibrariesDirectory | Libraries | The name of the directory where the libraries to be loaded into the Java Agent class path are located. Enter only the directory name — it is appended to the root installation directory. Required if `LibrariesInFile` is set to `N`. | +| JobStatusCheckInterval | 5 | The time in seconds to wait between status checks to determine if a job has completed processing. | +| JobStatusCheckInitialPollDelay | 5 | The time in seconds to wait before the initial status check to determine if a job has completed processing. | ## Example Agent.config @@ -143,3 +160,27 @@ JobStatusCheckInterval=5 JobStatusCheckInitialPollDelay=5 ``` + +## FAQs + +**What happens if SocketNumberToSAM does not match the socket number in OpCon?** +The agent and OpCon will not be able to communicate. Jobs will not start, and the machine will show as not connected in the Enterprise Manager. Ensure the value in `Agent.config` matches the socket number on the machine record in OpCon. + +**Why is job output not appearing in the View Job Output screen?** +The `CaptureJobOutput` setting must be set to `TRUE`. If it is set to `FALSE`, the agent does not write job output files and the View Job Output feature has no data to display. + +**Can I allow connections from multiple specific IP addresses?** +Yes. Use `AllowedIPAddress_1` through `AllowedIPAddress_5` to define up to five specific IP addresses. If you need unrestricted access, set `AllowedIPAddress_1` to `ANY`. + +**What does MaximumNumberOfJobs = 0 do?** +Setting `MaximumNumberOfJobs` to `0` prevents the agent from processing any jobs. Set this to `0` only if you want to temporarily disable job processing on the agent. + +## Glossary + +**Agent.config** — The configuration file for the Java Agent. It is located in the `\Java Agent [CPU]\` directory and controls all agent behavior, including network communication, job limits, library loading, and debug tracing. + +**SMANetCom** — The OpCon network communications component that sends job start, status check, and stop requests to agents. The `SocketNumberToSAM` value in `Agent.config` must match the socket number configured in OpCon for this communication to work. + +**JORS (Job Output Retrieval System)** — The OpCon mechanism for retrieving standard output and error logs from agent jobs after they complete. The `JORSSocket` port must be open between the agent and the OpCon server. + +**CaptureJobOutput** — The `Agent.config` setting that controls whether job output files are written to the `JobOutput` subdirectory. Must be `TRUE` for the View Job Output feature to work. diff --git a/docs/administration/overview.md b/docs/administration/overview.md new file mode 100644 index 0000000..02b85c5 --- /dev/null +++ b/docs/administration/overview.md @@ -0,0 +1,24 @@ +--- +sidebar_label: 'Administration overview' +title: Java Agent administration overview +description: "Overview of the Java Agent administration section, covering the Agent.config file settings for network communication, job limits, libraries, and debug options." +tags: + - Overview + - System Administrator + - Agents +--- + +# Administration overview + +## What is it? + +This section covers the configuration settings that control how the Java Agent operates. All settings are stored in the `Agent.config` file on the agent machine. + +- Use the configuration file reference when setting up the agent for the first time to verify required network and job settings +- Use the configuration file reference when troubleshooting connectivity, job output, or library loading issues + +## In this section + +| Page | Description | +|---|---| +| [Configuration file](./configuration-file.md) | Reference for all `Agent.config` settings: general settings (job limits), TCP/IP parameters (socket numbers, allowed IP addresses), process creation parameters (job output capture), debug options, JORS settings, and application connector settings | diff --git a/docs/index.md b/docs/index.md index dfd896c..56936d4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,16 +1,73 @@ --- slug: '/' sidebar_label: 'Java Agent' +hide_table_of_contents: true +displayed_sidebar: null --- -# Getting started +# Java Agent The Java Agent is an OpCon agent that allows OpCon to schedule Java classes and scripts or programs within a Java environment. -The current version is **21.0.0**. +
-Each Java class, script, or executable is executed as part of the Java Agent within a separate thread which is terminated when the execution is complete. When executing Java classes with named methods (non-main method), the execution is performed within a separate thread of the Java Agent JVM. When executing Java classes using the main method and scripts or executables, the execution is performed within a separate thread that spawns a separate JVM for the duration of the execution. Standard output and error logs are collected and appended to the job output information which is accessible from the OpCon environment using the JORS capability. +
-Parameters can be passed to the Java class methods and the script or executable. The parameters are defined using the job definition of the Java job. +
-For the Java Agent to execute a Java class, the library files (.jar files) required by the class must be loaded into the class path of the Java Agent. During the Java Agent startup, the library files (.jar files) are loaded into the class path. The Java Agent includes listeners that monitor for changes. When changes occur, the Java Agent will add the new information to the Java Agent class path. +### Overview + +- [Overview](./overview.md) +- [Release Notes](./release-notes.md) + +
+ +
+ +### Installation + +- [Installation](./installation/installation.md) + +
+ +
+ +
+ +
+ +### Administration + +- [Configuration file](./administration/configuration-file.md) + +
+ +
+ +
+ +
+ +### Operations + +- [Java classes](./operations/java-classes.md) +- [Scripts and executables](./operations/scripts-executables.md) +- [Managing software libraries](./operations/managing-software-libraries.md) + +
+ +
+ +
+ +
+ +### Reference + +- [Machine messages](./reference/machine-messages.md) + +
+ +
+ +
diff --git a/docs/installation/installation.md b/docs/installation/installation.md index 40985de..3b13b4e 100644 --- a/docs/installation/installation.md +++ b/docs/installation/installation.md @@ -1,106 +1,146 @@ -# Installation +--- +sidebar_label: 'Installation' +title: Java Agent installation +description: "How to install, upgrade, and configure the Java Agent on Windows, including service startup and machine creation in OpCon." +tags: + - Procedural + - System Administrator + - Agents +--- + +# Java Agent installation + +## What is it? + +The Java Agent installation package places the agent binaries, configuration files, and library directories on the target Windows machine and registers the agent as a Windows service. After installation, you create a machine record in OpCon to allow OpCon to communicate with the agent. + +- Use this procedure when setting up the Java Agent on a new Windows machine for the first time +- Use the upgrade procedure when updating an existing Java Agent to a newer release ## Requirements -Before beginning the installation, ensure that the system requirements are met. The supported software include: any supported version of Windows with .NET Framework 4.0 installed. +The following software must be present on the Windows machine before installation: -:::note -The Oracle JRE prerequisite has been removed from the installation package for this product. You must have a functional Java Runtime Environment installed prior to installation for this product to work. -::: +| Requirement | Details | +|---|---| +| Operating system | Any supported version of Windows | +| .NET Framework | Version 4.0 or later | +| Java Runtime Environment | A functional JRE must be installed separately — the Oracle JRE is no longer included in the installation package | ## New installation -The Java Agent can be installed within a 32- or 64-bit Windows system. To install a new Java Agent on a Windows system, complete the procedures in this section. +A complete new installation involves three sequential tasks: + +1. **Install the agent software** — run the installer and select the Java Agent component +2. **Configure service startup** — optionally adjust how the Windows service starts and which account it uses +3. **Create the machine in OpCon** — register the agent so OpCon can schedule jobs on it -### Agent installation +### Install the agent software -#### Install the Java Agent +To install the Java Agent, complete the following steps: 1. Log in to the Windows machine as a Local Administrator. -2. Exit all running applications on the desktop (including OpCon applications). -3. Double-click the **setup**.exe on the root of the OpCon installation media. The **Choose Setup Language** screen displays. -4. Select the desired language for the installation screens and click **Next**. The **Welcome** screen displays. -5. Click **Next**. The **Select Components** screen displays. -6. Select the Java Agent option based on your CPU type: - - **SMA OpCon Agents \> SMA OpCon Agent for Java x64** - - **SMA OpCon Agents \> SMA OpCon Agent for Java x86** -7. Click **Install**. The **Welcome** screen displays. -8. Click **Next**. The **Destination Folder** screen displays. -9. Change the target location for the installation or retain the default location. -10. Click **Next**. The **Select Path for Output Files** screen displays. -11. Change the directory for the output files or retain the default location. -12. Click **Next**. The **Setup Type** screen displays. -13. Select the Setup Type: **Complete** or **Custom**. -14. Click **Next**. The **Ready to Install the Program** screen displays. -15. Click **Install**. -16. Click **Finish** on the **InstallShield Wizard Completed** screen. -17. Refer to [Java Agent Configuration](../administration/configuration-file) to configure and operate the agent. +2. Exit all running applications on the desktop, including OpCon applications. +3. Open **setup.exe** on the root of the OpCon installation media. The **Choose Setup Language** screen displays. +4. Select the desired language and select **Next**. The **Welcome** screen displays. +5. Select **Next**. The **Select Components** screen displays. +6. Select the Java Agent option that matches your CPU type: + - **SMA OpCon Agents > SMA OpCon Agent for Java x64** — for 64-bit systems + - **SMA OpCon Agents > SMA OpCon Agent for Java x86** — for 32-bit systems +7. Select **Install**. The component installer opens and the **Welcome** screen displays. +8. Select **Next**. The **Destination Folder** screen displays. +9. Accept the default installation path or enter a new location, then select **Next**. The **Select Path for Output Files** screen displays. +10. Accept the default output path or enter a new location, then select **Next**. The **Setup Type** screen displays. +11. Select **Complete** or **Custom**, then select **Next**. The **Ready to Install the Program** screen displays. +12. Select **Install** to begin copying files. +13. Select **Finish** on the **InstallShield Wizard Completed** screen. :::note -The installation writes the log file named SMA_OpCon_Agent_for_Java__Install.log to the Windows directory. Consult this file if any installation problems are suspected. +The installer writes a log file named `SMA_OpCon_Agent_for_Java__Install.log` to the Windows directory. Consult this file if you suspect installation problems. ::: -### Service startup setup +After installation, refer to [Configuration file](../administration/configuration-file.md) to complete the agent configuration before starting the service. -By default, the Java Agent service is set for an Automatic (Delayed Start) startup and for running under the local system account. If you want to change the default settings, perform the procedure in this section. +### Configure service startup + +The Java Agent service defaults to **Automatic (Delayed Start)** startup under the local system account. Complete this procedure only if you need to change those defaults. :::caution -SMA recommends leaving the SMA OpCon Java Agent service set to Automatic (Delayed Start) to avoid potential issues at startup time while other services and programs start up. +SMA recommends keeping the service set to **Automatic (Delayed Start)**. Changing to plain **Automatic** can cause startup failures if other required services have not finished initializing. ::: -#### Set up service startup +To change the service startup settings, complete the following steps: -1. Use the following menu path on the Application server: **Start \> Control Panel \> Administrative Tools**. -2. Click the **Administrative Tools** icon. The **Administrative Tools** window displays. -3. Double-click the **Services** icon. The **Services** window displays. -4. Double-click the newly installed **SMA OpCon Java Agent \** service. The **SMA OpCon Java Agent \ Properties** dialog displays with the **General** tab in focus. -5. Select the **Service Startup type**: - - **Automatic (Delayed Start)** +1. Go to **Start > Control Panel > Administrative Tools** and open **Services**. +2. Open the **SMA OpCon Java Agent \** service. The **Properties** dialog displays with the **General** tab in focus. +3. Select the desired **Startup type**: + - **Automatic (Delayed Start)** *(recommended)* - **Automatic** - **Manual** - **Disabled** -6. Click on the **Log On** tab. -7. Select one of the following two **Log on as** options for the service: - 1. **Local System account**: If the service will run as the local system account, select this option to delete the default Domain User displayed in the text box. - 2. **This account**: If the service will run as a user because it needs access to network directories, enter a *Domain User* in the text box, enter the *Password* for the Domain User, and re-enter the *Password* to confirm. -8. Click the **OK** button. - -### Machine creation - -When a Java Agent is installed, create a machine record with a unique Machine name and Socket number in OpCon. If the machine was previously defined in OpCon, you may skip this procedure. - -#### Create the Machine in OpCon - -1. Use menu path: **Start \> Programs \> OpConxps \> Enterprise Manager**. The **OpCon Login** screen displays. -2. Enter a *case-sensitive User Login ID* (e.g., ocadm) in the **Username** text box. -3. Enter the *case-sensitive password for the user* in the **Password** text box. -4. Select the **profile** in the **Profile** drop-down list. -5. Click the **Login** button to log in to the Enterprise Manager. -6. Double-click on **Machines** under the **Administration** topic in the Navigation Panel. The **Machines** screen displays. -7. Click the **Add** button on the **Machines** toolbar. -8. Enter the *official host name or alias based on the Agent machine* in the **Name** text box. -9. Enter *any relevant documentation* for this Agent machine in the **Documentation** text box. -10. Select **Java** in the **Machine Type** drop-down list. -11. Set the *value* to a unique number (e.g., 3100) in the **Socket Number** box. -12. *(Optional)* Enter the *IPv4 or IPv6 address* in the **IP Address** field. -13. *(Optional)* Enter the *name* in the **Fully Qualified Domain Name** field. -14. Click the **Save** button on the **Machines** toolbar. -15. Click **Open Advanced Settings Panel** under the **Advanced Settings** frame. The **Advanced Machine Properties** dialog displays. -16. Click the **Java Settings** tab. -17. Configure the Java IP Address for the TCP/IP address of the Java system. -18. Click **Update**. -19. Configure the Java Socket Number for the port for communication with the Java machine. -20. Click **Update**. -21. Click **Save**. -22. *(Optional)* Start communication with the machine by: - 1. Right-clicking over the graphic to enable the menu in the **Communication Status** frame. - 2. Selecting **Start Communication** from the menu. -23. Click on the **x** to the right of the **Machines** tab to close the **Machines** screen. +4. Select the **Log On** tab. +5. Select the account the service will use: + - **Local System account** — select this option if the service does not need access to network directories + - **This account** — enter a *Domain User*, *Password*, and password confirmation if the service needs access to network directories +6. Select **OK**. + +### Create the machine in OpCon + +Create a machine record so OpCon can communicate with the newly installed agent. If this machine was previously defined in OpCon, skip this procedure. + +**Step 1 — Define the machine** + +1. Open **Start > Programs > OpConxps > Enterprise Manager** and log in. +2. Open **Machines** under the **Administration** topic in the Navigation Panel. +3. Select **Add** on the **Machines** toolbar. +4. Enter the agent machine's hostname or alias in the **Name** field. +5. Optionally enter documentation notes in the **Documentation** field. +6. Select **Java** in the **Machine Type** list. +7. Enter a unique port number (for example, `3100`) in the **Socket Number** field. +8. Optionally enter an IPv4 or IPv6 address in the **IP Address** field. +9. Optionally enter the fully qualified domain name in the **Fully Qualified Domain Name** field. +10. Select **Save** on the **Machines** toolbar. + +**Step 2 — Configure Java advanced settings** + +1. Select **Open Advanced Settings Panel** under the **Advanced Settings** frame. The **Advanced Machine Properties** dialog displays. +2. Select the **Java Settings** tab. +3. Enter the TCP/IP address of the Java system in the **Java IP Address** field, then select **Update**. +4. Enter the communication port number in the **Java Socket Number** field, then select **Update**. +5. Select **Save**. + +**Step 3 — Start communication (optional)** + +1. Right-select the graphic in the **Communication Status** frame to open the menu. +2. Select **Start Communication**. +3. Select **X** next to the **Machines** tab to close the screen. ## Upgrade installation -To upgrade the Java Agent, simply install the new package to the same directory as the previous installation. The installation package will preserve your configuration files automatically. +To upgrade the Java Agent, install the new package into the same directory as the previous installation. The installer preserves your existing configuration files automatically. ## Silent mode -To learn how to install the Java Agent in silent mode, refer to [Silent Mode](https://help.smatechnologies.com/opcon/core/installation/components#silent-mode) in the **OpCon Installation** online help. +To install the Java Agent without user interaction, refer to [Silent Mode](https://help.smatechnologies.com/opcon/core/installation/components#silent-mode) in the **OpCon Installation** online help. + +## FAQs + +**Can I install the Java Agent on a 32-bit Windows system?** +Yes. Select **SMA OpCon Agent for Java x86** during component selection. For 64-bit systems, select **SMA OpCon Agent for Java x64**. + +**What happens to my configuration files when I upgrade?** +The installer preserves your existing configuration files automatically when you install into the same directory as the previous installation. + +**What Java Runtime Environment do I need?** +You must install a functional JRE before running the Java Agent installer. The Oracle JRE is no longer bundled and must be installed separately. + +**Where is the installation log file written?** +The installer writes `SMA_OpCon_Agent_for_Java__Install.log` to the Windows directory. Review this file if the installation does not complete successfully. + +## Glossary + +**SMA OpCon Java Agent service** — The Windows service that runs the Java Agent process. It is registered during installation and controlled through Windows Services. + +**Socket number** — The TCP/IP port number used for communication between the Java Agent and OpCon's SMANetCom component. The value in `Agent.config` must match the socket number on the machine record in OpCon. + +**JORS (Job Output Retrieval System)** — The OpCon mechanism for capturing and retrieving job output logs from agent jobs. Requires the `JORSSocket` port to be open between the agent machine and the OpCon server. diff --git a/docs/installation/overview.md b/docs/installation/overview.md new file mode 100644 index 0000000..23e83c1 --- /dev/null +++ b/docs/installation/overview.md @@ -0,0 +1,25 @@ +--- +sidebar_label: 'Installation overview' +title: Java Agent installation overview +description: "Overview of the Java Agent installation section, covering new installation, service startup, machine creation, upgrade, and silent mode." +tags: + - Overview + - System Administrator + - Agents +--- + +# Installation overview + +## What is it? + +This section covers how to install and configure the Java Agent on a Windows system so that OpCon can communicate with it and schedule jobs. + +- Use the new installation procedure when setting up the Java Agent on a machine for the first time +- Use the upgrade procedure when updating an existing Java Agent to a newer release +- Use the silent mode reference when automating installations without user interaction + +## In this section + +| Page | Description | +|---|---| +| [Installation](./installation.md) | Step-by-step procedures for installing the agent, configuring the Windows service startup, creating the machine record in OpCon, upgrading an existing installation, and running the installer in silent mode | diff --git a/docs/operations/java-classes.md b/docs/operations/java-classes.md index b3537b8..2d9ae42 100644 --- a/docs/operations/java-classes.md +++ b/docs/operations/java-classes.md @@ -1,15 +1,32 @@ -# Executing Java classes +--- +sidebar_label: 'Java classes' +title: Running Java classes +description: "How the Java Agent runs Java classes using named methods or the main method, including parameter passing and type identifiers." +tags: + - Procedural + - Automation Engineer + - Agents +--- -When executing Java classes, the Java Agent should be installed on the same system as the Java classes that it should execute. The reason for this is that the Java Agent needs access to the Java libraries (.jar files) that contain the classes that will be executed as well as any additional libraries that the class requires to execute successfully. All these libraries need to be loaded into the class path of the Java Agent before the Java class can be executed successfully (refer to [Managing Software Libraries](managing-software-libraries)). +# Running Java classes -The Java Agent can execute classes that contain either a named method or the default main method of the class. +## What is it? + +The Java Agent runs Java classes defined in OpCon job definitions. It supports two entry points: a named method (any non-main method in the class) and the default main method. Parameters can be passed to either entry point from the OpCon job definition using typed identifiers. + +- Use named method when the class contains specific business logic methods you want OpCon to call directly +- Use main method when the class follows a standard command-line entry point pattern or accepts arguments as a string array + +When the Java Agent is installed on the same system as the Java classes, the agent needs access to the Java libraries (`.jar` files) that contain the classes. All required libraries must be loaded into the agent's class path before a job runs. For information on loading libraries, refer to [Managing Software Libraries](managing-software-libraries). + +The Java Agent can run classes that contain either a named method or the default main method of the class. ## Named method -When a named method (not default main method) is executed, parameters can be passed to the method as part of the method execution. The parameters that are passed to the method, must be defined using an identifier and a value. The supported identifiers are STRING, INTEGER, LONG and BOOLEAN. The Java Agent passes the parameters to the method casting them to the identified type using the identifier in the order that the parameters are defined in the job definition. +When a named method (not the default main method) runs, parameters can be passed to the method as part of the run. The parameters must be defined using an identifier and a value. The supported identifiers are `STRING`, `INTEGER`, `LONG`, and `BOOLEAN`. The agent passes the parameters to the method, casting them to the identified type using the identifier, in the order that the parameters are defined in the job definition. :::info Example -A Java class execution has a method execute which has four parameters defined as String, String, int, boolean objects. +A Java class `com.sma.test.execution` has a method `execute` with four parameters defined as `String`, `String`, `int`, and `boolean` objects. ::: ```java @@ -32,18 +49,18 @@ INTEGER 35 BOOLEAN True ``` -The Java Agent would execute the method mapping the parameters according to the identifiers as follows: +The Java Agent would run the method mapping the parameters according to the identifiers as follows: ```java com.sma.test.execution.execute("John", "Simpson", 35, true); ``` -## Main Method +## Main method -When a main method is executed, parameters can be passed to the method as part of the method execution. The parameters that are passed to the method, must be defined using either an identifier or a name and a value. If an identifier such as STRING, INTEGER, LONG and BOOLEAN is used, this is not passed as part of the execution. Otherwise, the name definition will be passed as part of the execution. The Java Agent passes the parameters to the method in the order that the parameters are defined in the job definition. +When a main method runs, parameters can be passed to the method as part of the run. The parameters must be defined using either an identifier or a name and a value. If an identifier such as `STRING`, `INTEGER`, `LONG`, or `BOOLEAN` is used, the identifier is not passed as part of the run — only the value is passed. If a name definition is used (for example, `-age`), the name is passed as part of the run. The agent passes the parameters to the method in the order that the parameters are defined in the job definition. :::info Example -A Java class execution has a main method and accepts multiple arguments. +A Java class `com.sma.test.execution` has a main method that accepts multiple arguments. ::: ```java @@ -66,8 +83,35 @@ STRING Simpson -male True ``` -The Java Agent would execute the main method passing the parameters as follows: +The Java Agent would run the main method passing the parameters as follows: ```java com.sma.test.execution "John" "Simpson" -age 35 -male True ``` + +## FAQs + +**What is the difference between a named method and the main method?** +A named method is any specific non-main method in a class that you want the agent to call directly. The main method is the standard Java entry point (`public static void main(String[] args)`). Named method runs happen within a thread of the agent's JVM. Main method runs spawn a separate JVM process. + +**What type identifiers does the Java Agent support?** +The agent supports `STRING`, `INTEGER`, `LONG`, and `BOOLEAN`. These identifiers tell the agent what Java type to use when passing the parameter value to the method. + +**Does the identifier appear in the method call for named methods?** +No. For named methods, the identifier is used only to determine the Java type for casting. The identifier itself is not passed to the method — only the value is passed, cast to the specified type. + +**Does the identifier appear in the command line for main method runs?** +No. When you use a type identifier (`STRING`, `INTEGER`, `LONG`, `BOOLEAN`) with a main method, only the value is passed as a command-line argument. When you use a name definition (for example, `-age`), both the name and the value are passed. + +**What happens if the class or method is not found?** +The agent logs an error message: `Method not found in class ` or `Class not found in libraries`. The job fails with an error return code. Verify that the required `.jar` files are loaded into the agent's class path. + +## Glossary + +**Named method** — A specific non-main method within a Java class, identified by name, that the agent calls directly. Parameters are passed using typed identifiers (`STRING`, `INTEGER`, `LONG`, `BOOLEAN`). + +**Main method** — The standard Java entry point method (`public static void main(String[] args)`). When using the main method, the agent spawns a separate JVM process. Parameters are passed as command-line arguments. + +**Type identifier** — A keyword (`STRING`, `INTEGER`, `LONG`, `BOOLEAN`) used in the OpCon job definition to specify the Java type for a parameter value. The agent casts the value to this type before passing it to the method. + +**Class path** — The list of directories and `.jar` files that the JVM searches when loading Java classes. All required libraries must be in the class path before a job runs. diff --git a/docs/operations/managing-software-libraries.md b/docs/operations/managing-software-libraries.md index 88bbf22..9d1ea44 100644 --- a/docs/operations/managing-software-libraries.md +++ b/docs/operations/managing-software-libraries.md @@ -1,11 +1,58 @@ +--- +sidebar_label: 'Managing software libraries' +title: Managing software libraries +description: "How to add and manage Java library files (.jar files) in the Java Agent class path, including directory and file-based configuration approaches." +tags: + - Procedural + - System Administrator + - Agents +--- + # Managing software libraries -For the Java Agent to execute a Java class, the library files (.jar files) required by the class must be loaded into the class path of the Java Agent. During the Java Agent start up, the library files (.jar files) are loaded into the class path by either placing a copy of the required .jar files in a defined library directory or entering the full path and filename in a file that the agent uses to determine where the .jar files are located (refer to [Java Agent Configuration](../administration/configuration-file)). +## What is it? + +For the Java Agent to run a Java class, the required library files (`.jar` files) must be loaded into the agent's class path before the job runs. The agent loads these libraries at startup and monitors them for changes, automatically updating the class path when new libraries are added. + +- Use the library directory approach when you want a simple, folder-based method of managing libraries — copy `.jar` files into the directory and the agent picks them up automatically +- Use the library file approach when you need precise control over which libraries are loaded and where they are located on the file system + +During the Java Agent startup, the library files (`.jar` files) are loaded into the class path by either placing a copy of the required `.jar` files in a defined library directory or entering the full path and filename in a file that the agent uses to determine where the `.jar` files are located. For configuration details, refer to [Java Agent Configuration](../administration/configuration-file). + +The Java Agent includes listeners that monitor either the directory containing the `.jar` files or the file listing the `.jar` file information for changes. When changes occur, the agent adds the new information to the class path automatically. + +## Adding libraries + +When adding a new Java job to the OpCon environment, all library files (`.jar` files) that the job requires must be added to the Java Agent that will run the job before the job is released. + +How you add the libraries depends on the Java Agent configuration. + +**If the LibrariesDirectory approach is configured:** +Copy the required `.jar` files to the defined library directory. The agent monitors the directory for changes. When new libraries are placed in the directory, they are automatically added to the existing class path. + +**If the LibrariesFileName approach is configured:** +Edit the file and add the full path and name of each library. The agent monitors the file for changes. When the file is updated, the agent reads it and automatically adds the new libraries to the existing class path. + +## FAQs + +**Do I need to restart the Java Agent after adding a new library?** +No. The agent monitors the library directory or library file for changes. When a new `.jar` file is added to the directory or the library file is updated, the agent automatically adds the new library to the class path without requiring a restart. + +**How do I know which approach my agent uses?** +Check the `LibrariesInFile` setting in the `Agent.config` file. If it is set to `N`, the agent uses the directory approach (`LibrariesDirectory`). If it is set to `Y`, the agent uses the file approach (`LibrariesFileName`). + +**What happens if a required library is missing when a job runs?** +The agent logs a `Library file not found` message during startup, or logs `Class not found in libraries` at run time. The job fails. Add the missing `.jar` file to the configured library directory or library file and verify it appears in the agent's class path before releasing the job. + +**Can I use both the directory and file approaches at the same time?** +No. The `LibrariesInFile` setting selects one approach. Set it to `N` to use the directory approach or `Y` to use the file approach. + +## Glossary -The Java Agent includes listeners that monitor either the directory containing the .jar files or the filename containing the .jar file information for changes. When changes occur, the Java Agent will add the new information to the Java Agent class path. +**Class path** — The list of directories and `.jar` files that the JVM searches when loading Java classes. The Java Agent builds and maintains this list from the configured library source at startup and updates it dynamically as new libraries are detected. -When adding a new Java Job to the OpCon environment, all library files (.jar files) that the job requires must be added to the Java Agent that will execute the job before the job is released. How to add the libraries to the Java Agent is dependent on the Java Agent configuration. +**LibrariesDirectory** — The `Agent.config` setting that defines the directory where `.jar` files are stored when using the directory approach. Only the directory name is entered — it is appended to the root installation directory. -If the *LibrariesDirectory* approach is being used the libraries must be copied to the defined directory. The Java Agent monitors the directory for changes and when new libraries are placed in the directory, the libraries will automatically be added to the existing class path. +**LibrariesFileName** — The `Agent.config` setting that defines the full path and name of the file listing library paths when using the file approach. Required when `LibrariesInFile` is set to `Y`. -If the *LibrariesFileName* approach is being used edit the file adding the full path and name of the libraries to the file. The Java Agent monitors the file for changes and when the file has been updated the file is read and the new libraries will automatically be added to the existing class path. +**LibrariesInFile** — The `Agent.config` setting that controls which library loading approach the agent uses. `N` uses the directory approach; `Y` uses the file approach. diff --git a/docs/operations/overview.md b/docs/operations/overview.md new file mode 100644 index 0000000..e863f25 --- /dev/null +++ b/docs/operations/overview.md @@ -0,0 +1,27 @@ +--- +sidebar_label: 'Operations overview' +title: Java Agent operations overview +description: "Overview of the Java Agent operations section, covering how to run Java classes, scripts, executables, and manage software libraries." +tags: + - Overview + - Automation Engineer + - Agents +--- + +# Operations overview + +## What is it? + +This section covers how to define and run jobs through the Java Agent. It includes running Java classes (named methods and main methods), running scripts and executables, and managing the library files the agent needs to run Java classes. + +- Use the Java classes page when defining OpCon jobs that call Java class methods or main methods +- Use the scripts and executables page when defining OpCon jobs that run `.exe`, `.com`, `.bat`, or `.sh` files through the agent +- Use the managing software libraries page when adding or updating the `.jar` files the agent needs for class-based jobs + +## In this section + +| Page | Description | +|---|---| +| [Java classes](./java-classes.md) | How the agent runs Java classes using named methods or the default main method, including parameter passing with type identifiers | +| [Scripts and executables](./scripts-executables.md) | How the agent runs scripts and executable files, supported file types, parameter passing, and Windows argument limits | +| [Managing software libraries](./managing-software-libraries.md) | How to add `.jar` files to the agent class path using the library directory or library file approach | diff --git a/docs/operations/scripts-executables.md b/docs/operations/scripts-executables.md index 8a147b2..6f4626b 100644 --- a/docs/operations/scripts-executables.md +++ b/docs/operations/scripts-executables.md @@ -1,13 +1,32 @@ -# Executing scripts or executables +--- +sidebar_label: 'Scripts and executables' +title: Running scripts and executables +description: "How the Java Agent runs scripts and executables, including supported file types, parameter passing, and Windows limitations." +tags: + - Procedural + - Automation Engineer + - Agents +--- -When executing scripts or executables, the Java Agent should be installed on the same system as the script or executable that it should execute. The Java Agent supports executing .exe, .com, .bat, and .sh file types. When using .com and .bat files types, there is a Windows limitation of nine arguments that can be passed to .com or .bat scripts. +# Running scripts and executables -When the script or executable is executed, parameters can be passed as part of the execution. The parameters that are passed to the script or executable, must be defined using either an identifier or a name and a value. If an identifier such as STRING, INTEGER, LONG and BOOLEAN is used, this is not passed as part of the execution. Otherwise, the name definition will be passed as part of the execution. The Java Agent passes the parameters to the script or executable in the order that the parameters are defined in the job definition. +## What is it? -:::info Example -A Java command execution c:\test\program.exe accepts multiple arguments. +The Java Agent runs scripts and executable files defined in OpCon job definitions. It supports `.exe`, `.com`, `.bat`, and `.sh` file types. Parameters can be passed to the script or executable from the OpCon job definition. + +- Use this capability when you need OpCon to schedule existing scripts or executables on the same system as the Java Agent +- Use `.sh` for shell scripts in a Java environment on Windows using a shell compatibility layer + +:::note +When using `.com` and `.bat` file types, there is a Windows limitation of nine arguments that can be passed to the script. ::: +When the script or executable runs, parameters can be passed as part of the run. Parameters must be defined using either an identifier or a name and a value. If an identifier such as `STRING`, `INTEGER`, `LONG`, or `BOOLEAN` is used, the identifier is not passed as part of the run — only the value is passed. If a name definition is used (for example, `-age`), both the name and the value are passed. The agent passes the parameters to the script or executable in the order that the parameters are defined in the job definition. + +## Example + +A Java command runs `c:\test\program.exe` and accepts multiple arguments. + The parameters for this would be defined in the Java job definition as follows: ``` @@ -22,3 +41,23 @@ The result would be: ``` C:\test\program.exe "John" "Simpson" -age 35 -male True ``` + +## FAQs + +**What file types does the Java Agent support for scripts and executables?** +The agent supports `.exe`, `.com`, `.bat`, and `.sh` file types. + +**Is there a limit on the number of arguments I can pass to a batch script?** +Yes. Windows limits `.com` and `.bat` files to nine arguments. If you need more than nine parameters, consider using an `.exe` or wrapping the script to read parameters from a file. + +**Does the type identifier appear in the final command line?** +No. When you use a type identifier (`STRING`, `INTEGER`, `LONG`, `BOOLEAN`), only the value is passed as a command-line argument. When you use a name definition (for example, `-age`), both the name and the value appear in the final command line. + +**Does the Java Agent need to be on the same machine as the script?** +Yes. The Java Agent runs scripts and executables on the machine where it is installed. The script file path in the job definition must be accessible from that machine. + +## Glossary + +**Command operation** — The Java Agent job operation type for running scripts and executables. It requires a directory path and a script or executable file name. + +**Type identifier** — A keyword (`STRING`, `INTEGER`, `LONG`, `BOOLEAN`) used in the OpCon job definition to pass a typed value to a script or executable. The identifier itself is not included in the command line — only the value is passed. diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..2762b15 --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,68 @@ +--- +sidebar_label: 'Overview' +title: Java Agent overview +description: "Overview of the Java Agent for OpCon, including what it does, use cases, and key concepts." +tags: + - Overview + - Automation Engineer + - Agents +--- + +# Java Agent overview + +## What is it? + +The Java Agent is an OpCon agent that allows OpCon to schedule Java classes and scripts or programs within a Java environment. It bridges OpCon's workload automation capabilities with Java-based application logic, enabling teams to run Java classes, JAR files, and scripts as managed OpCon jobs. + +- Use this agent when you need OpCon to schedule Java classes that contain business logic or batch processing routines +- Use this agent when you need to run existing scripts or executables (`.exe`, `.com`, `.bat`, `.sh`) from within a Java environment managed by OpCon +- Reduces manual intervention by allowing Java workloads to participate in OpCon schedules, dependencies, and event-driven automation +- Ensures job output and error logs are captured via JORS and accessible from the OpCon environment + +The current release is **21.0.0**. + +## How the Java Agent runs jobs + +Each Java class, script, or executable runs as part of the Java Agent within a separate thread that terminates when the run completes. + +- **Named method and non-main method classes**: The agent runs the job within a separate thread of the Java Agent JVM +- **Main method classes, scripts, and executables**: The agent runs the job within a separate thread that spawns a separate JVM for the duration of the run + +Standard output and error logs are collected and appended to the job output, which is accessible from the OpCon environment using the JORS capability. + +## Parameters + +Parameters can be passed to Java class methods and to scripts or executables. Parameters are defined in the job definition of the Java job. The agent passes parameters to named methods using typed identifiers: `STRING`, `INTEGER`, `LONG`, and `BOOLEAN`. For main method classes and scripts, parameters are passed as command-line arguments. + +## Class path and library management + +For the Java Agent to run a Java class, the required library files (`.jar` files) must be loaded into the agent's class path before the job runs. The agent loads these libraries at startup from either a configured library directory or a file listing library paths. The agent monitors both sources for changes and automatically updates the class path when new libraries are added. + +## FAQs + +**What Java operations does the agent support?** +The agent supports three operation types: Class (run a named method or main method in a Java class), JAR (run a JAR file with `-jar`), and Command (run a script or executable such as `.exe`, `.bat`, or `.sh`). + +**Does the agent support running multiple jobs at the same time?** +Yes. The `MaximumNumberOfJobs` setting in the `Agent.config` file controls how many jobs the agent can run concurrently. The default is 50. + +**How do I view job output?** +Job output is available through the JORS (Job Output Retrieval System) capability in OpCon, provided the `CaptureJobOutput` setting is set to `TRUE` in the `Agent.config` file. + +**Where are the library files stored?** +Library files can be stored in a configured library directory (default: `Libraries`) or listed in a file. The configuration is controlled by the `LibrariesInFile`, `LibrariesFileName`, and `LibrariesDirectory` settings in `Agent.config`. + +**What happens if a required library is not found?** +The agent logs a `Library file not found` message during startup. The job will fail at run time if it requires a library that is not in the class path. + +## Glossary + +**Java Agent** — The OpCon agent component that connects OpCon to a Java environment, enabling OpCon to schedule and monitor Java classes, JAR files, scripts, and executables as jobs. + +**Class path** — The list of directories and `.jar` files that the Java Virtual Machine (JVM) searches when loading Java classes. The agent manages this list at startup and updates it dynamically as libraries are added. + +**JORS (Job Output Retrieval System)** — The OpCon mechanism for capturing and retrieving standard output and error logs from agent jobs. Job output is accessible from the OpCon user interface when `CaptureJobOutput` is enabled. + +**Named method** — A specific method within a Java class, identified by name, that the agent calls instead of the default `main` method. Parameters are passed using typed identifiers (`STRING`, `INTEGER`, `LONG`, `BOOLEAN`). + +**Agent.config** — The configuration file for the Java Agent. It controls network settings, job limits, library paths, debug options, and JORS settings. diff --git a/docs/reference/machine-messages.md b/docs/reference/machine-messages.md index 194eaea..66615fe 100644 --- a/docs/reference/machine-messages.md +++ b/docs/reference/machine-messages.md @@ -1,66 +1,102 @@ -# Java Agent messages +--- +sidebar_label: 'Machine messages' +title: Java Agent machine messages +description: "Reference for all messages produced by the Java Agent during startup and job processing, including error messages and their meanings." +tags: + - Reference + - System Administrator + - Agents +--- -The agent output provides various messages when processing and these messages are written to the job output as well as the JavaAgent.log file. This section provides an overview of these messages and their meanings. +# Java Agent machine messages + +## What is it? + +The Java Agent produces messages during startup and job processing. These messages appear in the job output and in the `JavaAgent.log` file. Use this reference to identify what each message means and, where applicable, what action to take. + +- Use this reference when reviewing job output to understand the status of a job run +- Use this reference when troubleshooting agent startup failures or job failures caused by missing libraries or misconfiguration ## Java Agent startup messages -|Message|Description| +| Message | Description | |--- |--- | -|SMA Java Agent: ***version***|Displays the internal software version number associated with the Java Agent release.| -|library directory: ***directory name***|If the various .jar files to be loaded into the classpath are defined in a directory, the directory name is displayed.| -|Library File: ***filename***|If the various .jar files to be loaded into the classpath are defined in a file, the filename is displayed.| -|Classpath Loading Libraries from ***name***|Indicates where the various .jar files are being loaded from.| -|Adding library ***jar file name*** to the classpath|Indicates which .jar file is being loaded into the classpath.| -|Library file ***jar file name*** not found|Error message indicating if a defined .jar file is not found.| -|ERROR: Malformed URL Exception: could not load ***jar file name***|ERROR message indicating that the URL created to load the .jar file is an invalid format.| -|Classpath Load complete|Indicates the loading of the classpath is complete.| -|MaximumNumberOfJobs Set to: ***value***|Configuration information from the Agent.config file indicating the maximum number of concurrent jobs supported by the agent.| -|SocketNumberToSAM Set to: ***number***|The socket number used to communicate with OpCon.| -|JORSSocket Set to: ***number***|The socket number used by JORS to retrieve job output.| -|allowedIPAddress_1 Set to: ***value***|Allowed IP Addresses.| -|allowedIPAddress_2 Set to: ***value***|Allowed IP Addresses.| -|allowedIPAddress_3 Set to: ***value***|Allowed IP Addresses.| -|allowedIPAddress_4 Set to: ***value***|Allowed IP Addresses.| -|allowedIPAddress_5 Set to: ***value***|Allowed IP Addresses.| -|ConnectorName Set to: Java Agent|Displays the name of the Agent.| -|JobStatusCheckInterval Set to: ***number***|Displays the value to be used between checks when determining the status of a task.| -|JobStatusCheckInitialPollDelay Set to: ***number***|Displays the value to be used before the first check when determining the status of a task.| -|Starting Connector Java Agent|Message displayed to indicate that the Java Agent has started.| -|JORS Listening on port ***number***|The TCP/IP port used to listen for incoming JORS requests.| -|Agent Listening on port ***number***|The TCP/IP port used to listen for incoming OpCon requests.| - -## Java Agent task execution messages - -|Message|Description| +| `SMA Java Agent: ` | Displays the internal software version number associated with the Java Agent release. | +| `library directory: ` | If the `.jar` files to be loaded into the class path are defined in a directory, the directory name is displayed. | +| `Library File: ` | If the `.jar` files to be loaded into the class path are defined in a file, the filename is displayed. | +| `Classpath Loading Libraries from ` | Indicates where the `.jar` files are being loaded from. | +| `Adding library to the classpath` | Indicates which `.jar` file is being loaded into the class path. | +| `Library file not found` | Error: the specified `.jar` file was not found. Verify the file exists at the configured library path. | +| `ERROR: Malformed URL Exception: could not load ` | Error: the URL created to load the `.jar` file has an invalid format. Verify the library path in the configuration does not contain invalid characters. | +| `Classpath Load complete` | Indicates the class path loading is complete. | +| `MaximumNumberOfJobs Set to: ` | Configuration information from the `Agent.config` file indicating the maximum number of concurrent jobs supported by the agent. | +| `SocketNumberToSAM Set to: ` | The socket number used to communicate with OpCon. | +| `JORSSocket Set to: ` | The socket number used by JORS to retrieve job output. | +| `allowedIPAddress_1 Set to: ` | Allowed IP address 1. | +| `allowedIPAddress_2 Set to: ` | Allowed IP address 2. | +| `allowedIPAddress_3 Set to: ` | Allowed IP address 3. | +| `allowedIPAddress_4 Set to: ` | Allowed IP address 4. | +| `allowedIPAddress_5 Set to: ` | Allowed IP address 5. | +| `ConnectorName Set to: Java Agent` | Displays the name of the agent. | +| `JobStatusCheckInterval Set to: ` | Displays the interval in seconds between checks to determine whether a job has completed. | +| `JobStatusCheckInitialPollDelay Set to: ` | Displays the delay in seconds before the first status check to determine whether a job has completed. | +| `Starting Connector Java Agent` | Message displayed to indicate that the Java Agent has started. | +| `JORS Listening on port ` | The TCP/IP port used to listen for incoming JORS requests. | +| `Agent Listening on port ` | The TCP/IP port used to listen for incoming OpCon requests. | + +## Java Agent job processing messages + +| Message | Description | |--- |--- | -|Error: Invalid Operation = '***value***'|An operation other than Class or Command was received by the Agent.| -|Error: Class missing required definition - Class Library Name or Class Name|Either the library name (.jar file) or the java class name is missing from the requested Class Operation.| -|Error: Command missing required definition -Directory Name or Script/Exe Nam|Either the directory name or the Script/Exe name is missing from the requested Command Operation.| -|Executing: class ***class name***.main|The main method of the defined java class will be executed.| -|Executing: class ***class name***.***method name***|The defined method name within the defined class name will be executed.| -|Executing: script/exe ***directory name******file separator******script or executable***|The defined script or executable in the defined directory will be executed.| -|Job Error Fin: OpCon Return Code (***return code***)|The job encountered an error condition while executing.| -|Job Not Found: OpCon Return Code (***return code***)|The defined definition was not found in the classpath or in the directory.| -|Job ***OpCon unique jobid*** Cancelled|Job was cancelled by the Java Agent.| -|Entry ***OpCon unique jobid*** not found in hastable|During recovery when trying to track jobs defined in the tracking file, the OpCon job was not found in the active job agent table.| -|***timestamp***: Schedule (***schedule name***) Job (***job name***) was cancelled|The defined job was cancelled by the Java Agent.| -|***timestamp***: Schedule (***schedule name***) Job (***job name) was cancelled by OpCon Kill function|Job was cancelled by an OpCon 'kill' command.| -|***timestamp***: Schedule (***schedule name***) Job (***job name***) cancelled by OpCon Kill function failed, job not found|Job cancel command by OpCon 'kill' failed as the OpCon job could not be found in the active agent table.| -|***timestamp***: Schedule (***schedule name***) Job (***job name***) Completed with Return Code (***return code***)|Job completion message.| -|***timestamp***: ***name***|Java Agent identification message which appears in job output.| -|***timestamp***: Version: ***agent version***|Java Agent internal version number which appears in job output.| -|***timestamp***: FrameWork Version: ***application framework version***|Java Application Framework identification message which appears in job output.| -|***timestamp***: Jar File: ***jar file name***|Name of the jar file containing the class which appears in the output when a Class Operation is performed.| -|***timestamp***: Executing Class: ***class name***|Name of the class to execute which appears in the output when a Class Operation is performed.| -|***timestamp***: Method: ***method name***|Name of the method to execute which appears in the output when a Class Operation is performed. If the method name is omitted, it defaults to 'main'.| -|***timestamp***: Parameters: ***parameters***|Parameters to be passed to the method which appears in the output when a Class Operation is performed.| -|***timestamp***: Parameters: none|Appears in the output when a Class Operation is performed and no parameters are supplied for the methods.| -|***timestamp***: Method ***name*** not found in class ***name***|Error message that appears in the output when the method is not found in the defined class when a Class Operation is performed.| -|***timestamp***: Class ***name*** not found in libraries|Error message that appears in the output when the class name is not found in the defined library when a Class Operation is performed.| -|***timestamp***: Executing Class: ***class name*** completed with Return Code ***code***|Completion message that appears in the output when the Class Operation is completed.| -|***timestamp***: Executable Path: ***directory name***|Appears in the output when a Command Operation is performed and defines the full path to the filename that contains the executable/script to execute.| -|***timestamp***: Script/exe Name: ***name***|Appears in the output when a Command Operation is performed and defines the executable/script to execute.| -|***timestamp***: Job Output redirected to file ***filename***|Appears in the output when a Class or Command Operation is performed and defines the log file used to capture the job output log.| -|***timestamp***: Job ErrorLog redirected to file ***filename***|Appears in the output when a Class or Command Operation is performed and defines the error file used to capture the job error log.| -|***timestamp***: Exception ***exception***|Appears in the output when a Class or Command Operation is performed and the job encounters an exception.| -|***timestamp***: Problems creating redirected system out file ***filename*** Error: ***error***|Appears in the output when a Class or Command Operation is performed and the redirection file cannot be created.| +| `Error: Invalid Operation = ''` | An operation other than Class or Command was received by the agent. Verify the job definition in OpCon uses a supported operation type. | +| `Error: Class missing required definition - Class Library Name or Class Name` | Either the library name (`.jar` file) or the Java class name is missing from the requested Class operation. Verify the job definition includes both values. | +| `Error: Command missing required definition - Directory Name or Script/Exe Name` | Either the directory name or the script or executable name is missing from the requested Command operation. Verify the job definition includes both values. | +| `Executing: class .main` | The main method of the defined Java class will run. | +| `Executing: class .` | The defined method within the defined class will run. | +| `Executing: script/exe