docs: migrate HOIST HUB Documentation Standard to Docusaurus
This commit is contained in:
1 parent
ce58a0c6e0
commit
8b30e9405b
19 files changed
+966
No files matched your search
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"label": "HOIST HUB Documentation Standard",
|
||||
"position": 1,
|
||||
"collapsible": false
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Delivery & Governance",
|
||||
"position": 5
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Approvals & Deliverables
|
||||
---
|
||||
|
||||
# Approvals & Deliverables
|
||||
|
||||
## Approvals
|
||||
|
||||
This section is mandatory and must be completed in accordance with the established process for every specification, as it captures the initial approval. The Hoist Business Analyst is responsible for obtaining this sign-off. Any approvals for subsequent changes will be recorded in the Change Log section.
|
||||
|
||||
### Functional Design Definition Approved
|
||||
|
||||
| Approver | Date Approved | Artifact | Change No. |
|
||||
|----------|--------------|----------|------------|
|
||||
| | | | |
|
||||
|
||||
### Technical Design & Estimate Approved
|
||||
|
||||
The TSM is responsible for getting this sign-off.
|
||||
|
||||
| Approver | Date Approved | Artifact | Change No. |
|
||||
|----------|--------------|----------|------------|
|
||||
| | | | |
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
This section, owned by the developer, documents the final deliverables of the task. It must specify:
|
||||
|
||||
- The components included in the delivery
|
||||
- The delivery format (e.g., Delivery Build, Application Configuration Package (ACP), or Manual Deployment with instructions)
|
||||
- For ACP deliveries: the name of the ACP
|
||||
- For deliveries uploaded to DevOps (IFS Cloud): the specific folder within the Build Home structure where the files are located
|
||||
|
||||
---
|
||||
|
||||
## Delimitations & Dependencies
|
||||
|
||||
The configurations in this specification have been configured as documented. Requests for changes in the configuration necessary to fulfil (or prepare for future fulfilment of) any requirements not explicitly described in the business requirements specification will be considered outside the scope of this configuration.
|
||||
|
||||
The following are excluded from this specification:
|
||||
|
||||
- Translations other than stated under the translations chapter
|
||||
- Changes or extensions on Online Help (F1 Help), e-learning material, or process models
|
||||
|
||||
Document what is **NOT** covered by this specification, including functionality that will not be implemented. If you refer to external documents, make sure to include them either in the Appendices or in the Foundation for Functional Specification section.
|
||||
|
||||
---
|
||||
|
||||
## Go-Live Information / Upgrade Issues
|
||||
|
||||
Enter vital go-live information if appropriate, e.g.:
|
||||
|
||||
- Basic data setup
|
||||
- Scheduled tasks
|
||||
- Permission Sets
|
||||
- Whether upgrade scripts are required or manual data updates in IFS Applications are needed when the configuration is installed
|
||||
|
||||
*Delete this section if not applicable.*
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
This section is owned by the developer. Provide guidance on data volumes for the main tables. Does not need to be precise but should give an order of magnitude.
|
||||
|
||||
**Example:** The volume of data within the new functions is unlikely to be high. Typically, there could be several hundred X records and up to 10,000 Y entries each. There are no expected issues with high volume processing or large tables to be considered in the design and coding.
|
||||
|
||||
*Delete this section if not applicable.*
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Change Log
|
||||
---
|
||||
|
||||
# Change Log
|
||||
|
||||
:::danger
|
||||
Very Important
|
||||
This section is **exclusively** for recording all subsequent changes to the delivered HUB feature, encompassing change requests, requirement misunderstandings, and bug fixes.
|
||||
:::
|
||||
|
||||
Each change — whether a change request, requirement misunderstanding, or bug fix — must be documented as a new entry with the same level of detail as the original Sub-Function section of the specification. The **original Sub-Function section must remain unchanged** to ensure the initial requirements remain visible.
|
||||
|
||||
Every entry should provide:
|
||||
|
||||
- A concise, high-level explanation of the reason for the modification
|
||||
- The affected design sections, using clear tags or markers to highlight changes in lengthy specifications
|
||||
- An explicit indication of whether the entry addresses a **bug fix**, a **requirement misunderstanding**, or a **customer-requested change**
|
||||
|
||||
---
|
||||
|
||||
## Document Revision History
|
||||
|
||||
| Revision | Date | Author | Remarks |
|
||||
|----------|------|--------|---------|
|
||||
| 1 | 2026-03-17 | Najib El-Husseini | Initial Draft |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Description — Change #1
|
||||
|
||||
Take the required sections from the Business Requirements Definition, Functional Design Definition, and Technical Design Definition to properly document the full change to this HUB feature. Include new test plans for the updated functionality.
|
||||
|
||||
---
|
||||
|
||||
## Detailed Description — Change #n
|
||||
|
||||
Take the required sections from the Business Requirements Definition, Functional Design Definition, and Technical Design Definition to properly document the full change to this HUB feature. Include new test plans for the updated functionality.
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Estimates
|
||||
---
|
||||
|
||||
# Estimates
|
||||
|
||||
The PM is responsible for the number of hours estimated for this HUB feature. The technical and functional resources will tell the PM their individual estimates and the PM will enter that combined number here.
|
||||
|
||||
This estimate includes:
|
||||
|
||||
- The time required to detail the requirements and functional design in this document
|
||||
- The time required to hand over and discuss the requirements to the developer
|
||||
- The time required to detail the technical design in this document
|
||||
- The time required by the HOIST developer to develop the solution and delivery artifacts
|
||||
- The time required by the HOIST developer to perform technical testing
|
||||
- The time required by the HOIST business analyst to perform functional testing
|
||||
- The time required by the HOIST business analyst to perform testing with the client
|
||||
|
||||
---
|
||||
|
||||
## T-Shirt Estimate
|
||||
|
||||
This section is used to specify a rough estimate for the development of the features specified in this HUB Spec. This estimate is given before any detailed business requirements have been captured and will be based on the QTY per type of HUB feature (New Module, Page, Field, Feature), but will not reflect details regarding how difficult or simple the implementation will be.
|
||||
|
||||
| Size | HUB Type (Example) | Hours |
|
||||
|------|--------------------|-------|
|
||||
| XS | Extra Small | 4 |
|
||||
| S | Small | 8 |
|
||||
| M | Medium | 16 |
|
||||
| L | Large | 40 |
|
||||
| XL | Extra Large | 80 |
|
||||
| EPIC | EPIC | 100+ |
|
||||
|
||||
### HUB T-Shirt Estimates
|
||||
|
||||
| HUB # | Description | Size | Total Hours |
|
||||
|-------|-------------|------|-------------|
|
||||
| 1 | Sales Quotation | Epic | 24 |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Estimate
|
||||
|
||||
| HUB Obj # | Description | Estimator(s) | Estimate Type | Estimated Hours |
|
||||
|-----------|-------------|-------------|---------------|-----------------|
|
||||
| | Detail Requirements | | Func. | |
|
||||
| | Func. / Tech. Collab. | | Func. / Tech. | |
|
||||
| | Detail Requirements | | Tech. | |
|
||||
| | Development | | Tech. | |
|
||||
| | Testing | | Tech. | |
|
||||
| | Testing | | Func. | |
|
||||
| | Delivery | | Tech. | |
|
||||
| | Testing | | Func. | |
|
||||
| | Client Testing | | Func. | |
|
||||
| **TOTAL:** | | | | |
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Test Plan
|
||||
---
|
||||
|
||||
# Test Plan
|
||||
|
||||
## Technical & Unit Testing
|
||||
|
||||
Developers are required to thoroughly test HUB functionality by evaluating parameters such as null values, edge cases, and all potentially valid inputs against the technical specifications and requirements. Testing must confirm that no error messages are generated. Additionally, developers should perform regression testing between version changes to ensure that all existing HUB functionality remains correct and unaffected.
|
||||
|
||||
| Business Req # | HUB Obj # | Step # | Step Description | Test Data Input | Expected Result | Actual Result | Tester | Date Tested | Environment Tested |
|
||||
|----------------|-----------|--------|-----------------|-----------------|-----------------|---------------|--------|-------------|-------------------|
|
||||
| | | | | | | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Business Test Plan
|
||||
|
||||
This section details the testing procedures to verify that the HUB spec fulfills the business requirements outlined in the specification. Test plans must directly align with these requirements to confirm their successful implementation.
|
||||
|
||||
Testing instructions should be:
|
||||
|
||||
- Clear and step-by-step
|
||||
- Accessible to individuals unfamiliar with the solution
|
||||
- Include specific basic data (sample inputs or datasets) for reliable and repeatable outcomes
|
||||
|
||||
Collaboration between the HOIST Business Analyst and the customer is essential to develop accurate and mutually agreed-upon test plans.
|
||||
|
||||
| Business Req # | Test # | Step # | Step Description | Test Data Input | Expected Result | Actual Result | Tester | Date Tested | Environment Tested |
|
||||
|----------------|--------|--------|-----------------|-----------------|-----------------|---------------|--------|-------------|-------------------|
|
||||
| | | | | | | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Client / User Testing
|
||||
|
||||
This section is designed for use by the customer during the customer testing phase. The table in this section must align with the table in the Functional Results section above.
|
||||
|
||||
Successful testing of the HUB feature confirms that it has been developed and delivered as specified. Any changes or additional requirements should be documented in the Change Log section.
|
||||
|
||||
| Business Req # | Test # | Step # | Step Description | Test Data Input | Expected Result | Actual Result | Tester | Date Tested | Environment Tested |
|
||||
|----------------|--------|--------|-----------------|-----------------|-----------------|---------------|--------|-------------|-------------------|
|
||||
| | | | | | | | | | |
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "IFS Integration",
|
||||
"position": 3
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: IFS Integration
|
||||
---
|
||||
|
||||
# Integration with IFS
|
||||
|
||||
Integration with IFS is a crucial part of HOIST Hub Design. Most HOIST HUB applications function in conjunction with or on top of IFS data sources. Therefore, tight IFS integration is required for most projects.
|
||||
|
||||
IFS integration is done via an **IFS Wrapper Module** that works as a low-code representation of the IFS Integration extension written in C#.
|
||||
|
||||
## Background
|
||||
|
||||
In previous projects, the IFS extension was a one-to-one representation of the required API calls. For example, if we needed to get customer information, we would have to create an extension method that calls the designated projection and endpoint based on specific query parameters. This was useful at first but proved to be too cumbersome as projects grew — many extension methods were added for every needed projection, and navigating them became a global pain.
|
||||
|
||||
The solution was to introduce new **generic API server actions** that work as general wrappers and, when fed the correct parameters, return the desired server response in text format that can later be deserialized as needed. These server actions work exactly the same as any native OutSystems server action, keeping true to the low-code nature of the platform.
|
||||
|
||||
:::info
|
||||
This is the **new and recommended** way to communicate with IFS's ODATA REST API. It is discouraged to write specific representations of IFS API calls in the IFS API Extension wrapper unless necessary for edge case scenarios that require complex logic that cannot be done in low-code (e.g., creating a virtual structure that requires cleanup). Creating new extension methods requires approval from your tech lead.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## IFS Generic Wrapper Server Actions
|
||||
|
||||
### `GetIfsGenericResultSet`
|
||||
|
||||
An `HttpGet` wrapper that calls the required endpoint and returns an IFS ResultSet as a JSON string. It requires basic knowledge of IFS ODATA REST APIs.
|
||||
|
||||
| Parameter | Direction | Description |
|
||||
|-----------|-----------|-------------|
|
||||
| IfsSettings | In | IfsSettings Object used to validate IAM Client and fetch Bearer Token |
|
||||
| IfsQueryParams | In | OutSystems representation of ODATA Query parameters |
|
||||
| Projection | In | Projection Name |
|
||||
| Endpoint | In | Endpoint that needs to be called — do not add URL parameters here, use IfsQueryParams instead |
|
||||
| Result | Out | JSON String that needs to be deserialized to the expected result |
|
||||
| TotalCount | Out | Returns the total count if specified by the IfsQueryParams object |
|
||||
|
||||
**Documentation requirements when using `GetIfsGenericResultSet`:**
|
||||
|
||||
Developers are required to add a meaningful description that contains:
|
||||
|
||||
- The purpose of the API call
|
||||
- The expected data structure to be retrieved from IFS
|
||||
- IFS query parameters, target endpoint, and/or conditions used in detail
|
||||
|
||||
The server action should be named in a meaningful way that prevents ambiguity. If the server action is used inside a screen or a data action, a reference to the purpose of the API call should be mentioned in the screen/data action documentation.
|
||||
|
||||
It is also optional but encouraged to add a comment of the description in the server action body for other developers.
|
||||
|
||||
**Technical document format:**
|
||||
|
||||
| Server Action Name | Description and Guidance |
|
||||
|-------------------|--------------------------|
|
||||
| Parameter Name | Direction | Data Type/Length | Description |
|
||||
| Parameters | I | | |
|
||||
|
||||
**Example:**
|
||||
|
||||
| GetCaseById | Gets a case from IFS by KeyRef |
|
||||
|-------------|-------------------------------|
|
||||
| CaseId - Mandatory | In | Text | Case Id to be retrieved |
|
||||
| IfsSettings - Mandatory | In | IfsSettings Struct | IFS IAM Client Settings |
|
||||
| CcCase | Out | CcCase Struct | CcCase Structure retrieved from IFS |
|
||||
|
||||
---
|
||||
|
||||
## IFS API Frequently Used Structures
|
||||
|
||||
### `IfsSettings`
|
||||
|
||||
Contains the needed information to communicate with an IFS instance. Fully supports cloud and, to a certain extent, Apps10 versions of IFS.
|
||||
|
||||
| Property | Data Type | Description |
|
||||
|----------|-----------|-------------|
|
||||
| BaseUrl | Text | IFS's base URL |
|
||||
| User | Text | Username, used for APPS10 |
|
||||
| Password | Text | Password, used for APPS10 |
|
||||
| UseMain | Boolean | Legacy, always true — INT layer no longer supported |
|
||||
| ClientId | Text | IAM Client ID |
|
||||
| ClientSecret | Text | IAM Client Secret |
|
||||
| Token | Text | AccessToken auto-generated by IFS |
|
||||
| TokenEndpoint | Text | IFS Token Endpoint |
|
||||
| RefreshToken | Text | RefreshToken, auto-generated by IFS |
|
||||
| IfsVersion | Text | `10` = APPS10, `cloud` = CLOUD |
|
||||
| Realm | Text | Used for IFS Cloud |
|
||||
| AcquiredOn | DateTime | Token acquired on date |
|
||||
| UseExternalApiProvider | Boolean | Used to identify if this is a direct IFS connection or uses an API Layer |
|
||||
|
||||
---
|
||||
|
||||
### `IfsQueryParams`
|
||||
|
||||
A structure that represents the most common parameters to query IFS ODATA REST APIs. Used to construct the URL with the correct parameters.
|
||||
|
||||
| Property | Data Type | Description |
|
||||
|----------|-----------|-------------|
|
||||
| Filter | Text List | Appended to the URL with the `$filter` query parameter using AND operator. If OR operator is needed, wrap between `(` and `)`, e.g.: `(CustomerId eq 'xxx' or CustomerId eq 'yyy')`. Requires knowledge of ODATA filter operators. |
|
||||
| Select | Text List | Translated to a comma-separated value for `$select`. Use to select relevant fields; if empty, all fields including custom fields will be selected. |
|
||||
| Expand | Text List | Translated to a comma-separated value for `$expand`. Use to expand relevant navigation entities. |
|
||||
| OrderBy | Text List | Translated to a comma-separated value for `$orderby`. Can be ascending (`asc`) or descending (`desc`). |
|
||||
| Skip | Int | Number of rows to skip — used with `$skip`. |
|
||||
| Take | Int | Number of rows to take — used with `$top`. |
|
||||
| FetchCount | Boolean | If `true`, sets `$count=true`. Avoid if not needed, as it slows the query. |
|
||||
| TimeoutSeconds | Int | Number of seconds before the request times out. Default is 120. |
|
||||
| TimezoneAwareRequest | Boolean | If `true`, the request is sent with a timezone awareness header and response dates are returned in Universal Time Zone. |
|
||||
| ApplyFunction | String | Custom function for `$apply` query parameters. Advanced — useful for aggregates like sum and count. |
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Overview",
|
||||
"position": 1
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Purpose & Guidance
|
||||
---
|
||||
|
||||
# Purpose & Guidance
|
||||
|
||||
This document specifies how the defined functions shall be developed or how the application shall be customized to solve the business requirements.
|
||||
|
||||
The **Solution Description** defines what will be delivered. The solution is matched against the requirements described in the Requirements section.
|
||||
|
||||
The **Delimitations** describe what is explicitly not covered by this spec. Together with the Solution description, these sections delimit the extent of the functional addition agreed for implementation.
|
||||
|
||||
The **Business Requirements and References** describe the business problem(s) to be resolved by this HUB spec. This section should be completed by a representative of the business user. The language of this section is aimed at capturing the desired outcomes and is less concerned with how those outcomes will be achieved.
|
||||
|
||||
:::tip[Important Reminders]
|
||||
- Green texts include guidance and examples — remove them as the specification is written.
|
||||
- Remove sections that do not apply.
|
||||
- Spell and grammar check the document each time you save it and before it goes to the customer.
|
||||
- Strict adherence to the initial and change order sign-off processes. No work/changes/fixes are given to developers before this step.
|
||||
:::
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Process Roles & Responsibilities
|
||||
---
|
||||
|
||||
# Process Roles & Responsibilities
|
||||
|
||||
## Customers
|
||||
|
||||
Customers are responsible for understanding the business and/or IFS process and how the HUB spec applies to their specific solution. Before granting approval, the Customer must thoroughly review the document and ensure they fully comprehend its contents. We encourage customers to ask questions or seek clarification during this stage to avoid any misunderstandings.
|
||||
|
||||
Approval is a critical step, and we value the customer's input and feedback. However, once approval is granted, any legitimate requirements not identified during this stage — regardless of how they were overlooked — will be considered a change to the scope and may require additional agreements.
|
||||
|
||||
## Hoist Business Analyst
|
||||
|
||||
The Hoist Business Analyst acts as the primary point of contact between the Customer and the Hoist HUB Developer, ensuring that all communication is streamlined and efficient. To maintain clarity and avoid potential miscommunication, the customer should not have direct contact with the Hoist Developer. All communication must be routed through the Hoist Business Analyst to ensure that the documentation and re-sign off processes are strictly followed.
|
||||
|
||||
They handle any questions the Hoist Developer might have regarding the desired functionality, either providing answers directly or sourcing them as needed. Additionally, the Hoist Business Analyst is responsible for creating the test steps and then collaborates with the Hoist Developer to conduct preliminary testing before the HUB feature is delivered to the customer for final testing.
|
||||
|
||||
## Hoist Developer (DEV)
|
||||
|
||||
The Hoist Developer is responsible for the content of the Technical Design Definition. They will provide technical estimates, develop according to specifications, and create the required deliveries. The Hoist Developer will work with the Hoist Business Analyst to understand the required solution and offer guidance on the requested solution's feasibility and offer alternatives if the solution is determined to be problematic or inefficient.
|
||||
|
||||
:::warning
|
||||
It is crucial that the Hoist Business Analyst does not commit to a feature with the customer before ensuring feasibility with the Hoist Technical Solution Manager or Hoist Lead Developer. Any feature that is not discussed with the development lead before committing to the client will be ignored.
|
||||
:::
|
||||
|
||||
## Hoist Project Manager (PM)
|
||||
|
||||
The Hoist Project Manager is responsible for communicating the estimates and SOW to the appropriate leadership in the client business. They are responsible for getting the approvals and updating this document's approval section with the appropriate information and saved artifacts (email, pdf, etc.)
|
||||
|
||||
## Technical Solution Manager (TSM)
|
||||
|
||||
The HOIST Technical Solution Manager is responsible for providing oversight and management of technical aspects. This includes coordination of technical resources and managing development work and priorities.
|
||||
|
||||
## HUB Delivery Lead
|
||||
|
||||
The HOIST HUB Delivery Lead is responsible for the overall solution and technical direction, providing oversight and management of both application and technical aspects. This includes the review and approval of all HUB specs before development commences.
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Process Standards",
|
||||
"position": 2
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Custom Fields
|
||||
---
|
||||
|
||||
# Custom Fields Documentation Standard
|
||||
|
||||
Custom fields must be explicitly documented, especially when they are integrated with or sourced from external systems (e.g., IFS).
|
||||
|
||||
## Definition and Scope
|
||||
|
||||
Each custom field must be clearly identified as custom (i.e., non-core or non-standard). The documentation must specify:
|
||||
|
||||
- The external system it is connected to (if applicable)
|
||||
- Whether the field is optional, conditional, or mandatory
|
||||
|
||||
Custom fields may not be applicable across the entire application and may vary by:
|
||||
|
||||
- Portal owner
|
||||
- Tenant
|
||||
- Deployment context
|
||||
|
||||
## Applicability and Visibility
|
||||
|
||||
Documentation must clearly state:
|
||||
|
||||
- Which portal owners or user groups can see or use the field
|
||||
- Any conditions that control visibility or availability
|
||||
|
||||
If a custom field is only relevant in specific modules, flows, or screens, this must be explicitly stated.
|
||||
|
||||
## Behavior and Constraints
|
||||
|
||||
The business purpose of each custom field must be documented. Any constraints or special behavior should be described, including:
|
||||
|
||||
- Validation rules
|
||||
- Read-only or system-managed values
|
||||
- Dependency on external system data availability
|
||||
|
||||
## External System Dependency
|
||||
|
||||
For fields connected to external systems:
|
||||
|
||||
- Clearly define the source of truth
|
||||
- Describe synchronization behavior (real-time vs. asynchronous)
|
||||
- Document fallback or error behavior if the external system is unavailable
|
||||
|
||||
## Impact on UI and Integration
|
||||
|
||||
The presence or absence of custom fields must not negatively impact standard application behavior. Any UI or integration logic that depends on custom fields must be clearly documented to avoid assumptions in shared or multi-tenant environments.
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Mockups & Screenshots
|
||||
---
|
||||
|
||||
# Mockups & Screenshots Documentation Standard
|
||||
|
||||
Mockups and screenshots are mandatory artifacts used to visually communicate screen behavior, layout, and user interactions. They must complement — not replace — written documentation and be consistent with the defined UI Flow and business logic.
|
||||
|
||||
## Purpose and Scope
|
||||
|
||||
Mockups/screenshots must clearly illustrate:
|
||||
|
||||
- Screen layout and structure
|
||||
- Key user interactions and navigation paths
|
||||
- Differences between List and Detail views
|
||||
- Variations across screen modes (e.g., View, Edit, Create)
|
||||
|
||||
Visual assets should reflect the intended final behavior, not exploratory or experimental designs unless explicitly stated.
|
||||
|
||||
---
|
||||
|
||||
## Mockup Requirements
|
||||
|
||||
### Level of Fidelity
|
||||
|
||||
**High-fidelity mockups** are preferred for:
|
||||
- New screens
|
||||
- Complex user interactions
|
||||
- Approval-ready specifications
|
||||
|
||||
**Low- or mid-fidelity mockups** are acceptable for:
|
||||
- Early discovery phases
|
||||
- Internal alignment or conceptual discussions
|
||||
|
||||
:::note
|
||||
Low/mid-fidelity mockups must be clearly labeled as **non-final**.
|
||||
:::
|
||||
|
||||
### Consistency
|
||||
|
||||
Mockups must align with:
|
||||
|
||||
- Design system / UI guidelines
|
||||
- Naming conventions used in documentation
|
||||
- Field labels, actions, and terminology defined in the spec
|
||||
|
||||
Any intentional deviation from standards must be explicitly documented.
|
||||
|
||||
### Coverage
|
||||
|
||||
Mockups should cover, at minimum:
|
||||
|
||||
- List View (default state)
|
||||
- Detail View (view-only mode)
|
||||
- Detail View (edit/create mode)
|
||||
- Empty states (no data)
|
||||
- Error or validation states (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## Screenshot Standards
|
||||
|
||||
### When to Use Screenshots
|
||||
|
||||
Screenshots may be used when:
|
||||
|
||||
- Documenting existing or legacy functionality
|
||||
- Validating implemented behavior against specifications
|
||||
- Providing references for enhancements or bug fixes
|
||||
|
||||
### Quality and Clarity
|
||||
|
||||
Screenshots must:
|
||||
|
||||
- Be clear, legible, and high resolution
|
||||
- Exclude irrelevant UI elements or personal data
|
||||
- Highlight the relevant area using annotations if needed
|
||||
|
||||
---
|
||||
|
||||
## Annotation and Labeling
|
||||
|
||||
All mockups and screenshots must include:
|
||||
|
||||
- Screen name and version
|
||||
- Mode or state (e.g., List, Detail – Edit)
|
||||
|
||||
Annotations should be used to:
|
||||
|
||||
- Explain business rules
|
||||
- Clarify hidden or dynamic behavior
|
||||
- Call out permissions, validations, or conditional visibility
|
||||
|
||||
Annotations must be concise and consistent with written documentation terminology.
|
||||
|
||||
---
|
||||
|
||||
## Traceability and Referencing
|
||||
|
||||
Each mockup or screenshot must:
|
||||
|
||||
- Be referenced explicitly in the documentation (e.g., "See Mockup M-01")
|
||||
- Map clearly to documented requirements, flows, or actions
|
||||
|
||||
If multiple screens share similar layouts or behavior, this should be stated to avoid redundancy.
|
||||
|
||||
---
|
||||
|
||||
## Versioning and Maintenance
|
||||
|
||||
Mockups and screenshots must be versioned and updated with:
|
||||
|
||||
- Functional changes
|
||||
- UI changes impacting user behavior
|
||||
|
||||
Outdated visuals must not remain referenced in active documentation. Version history or change notes should be maintained when mockups are updated.
|
||||
|
||||
---
|
||||
|
||||
## Tools and Formats
|
||||
|
||||
| Format | Accepted |
|
||||
|--------|----------|
|
||||
| PNG | Yes |
|
||||
| JPG | Yes |
|
||||
| Figma (embedded link) | Yes |
|
||||
|
||||
Source design files should be accessible to relevant stakeholders when possible. Screenshots embedded in documentation must preserve original aspect ratios.
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: UI Flow Development
|
||||
---
|
||||
|
||||
# UI Flow Development
|
||||
|
||||
## Quick Overview
|
||||
|
||||
A UI Flow can be either:
|
||||
|
||||
- A **standalone flow**, where each module contains a single screen, or
|
||||
- A **composite flow**, which is more common and consists of multiple screens per module.
|
||||
|
||||
Regardless of the flow type, the standard design pattern is to provide both a **List View** and a **Detail View** within the same flow.
|
||||
|
||||
To optimize application object usage, the List and Detail views should be implemented on the same screen, even for complex flows. The behavior should be controlled through an input parameter named `mode`, which clearly defines the screen state (e.g., `list` vs. `detail`).
|
||||
|
||||
## Documentation Standard
|
||||
|
||||
Each screen and its associated blocks must be documented within a single specification/documentation file.
|
||||
|
||||
The documentation must include:
|
||||
|
||||
- A detailed explanation of the business flow
|
||||
- Clear descriptions of expected user interactions, including mandatory fields, links to other screens, and button functionality
|
||||
- Any assumptions or constraints related to usage
|
||||
|
||||
---
|
||||
|
||||
## List View Documentation Requirements
|
||||
|
||||
### Filters
|
||||
|
||||
- A detailed explanation of all available filters within the screen
|
||||
- The purpose and behavior of each filter
|
||||
- Whether the filter fires automatically or requires additional user interaction
|
||||
|
||||
### Actions and Navigation
|
||||
|
||||
A description of all supported actions and navigation paths, including:
|
||||
|
||||
- **Global actions** — affecting the entire screen
|
||||
- **Row-level actions** — specific to individual records
|
||||
|
||||
### Permissions
|
||||
|
||||
- A clear definition of the permissions applicable within the screen context as defined by the HUB standard Profile Permissions
|
||||
- Explanation of how permissions affect visibility, actions, or navigation
|
||||
|
||||
### External System Mapping
|
||||
|
||||
If the screen is integrated with an external system, a separate mapping table must be included. The mapping should clearly define field relationships and data flow between systems.
|
||||
|
||||
---
|
||||
|
||||
## Detail View Documentation Requirements
|
||||
|
||||
The Detail View documentation must clearly describe how users interact with a single record and how the screen behaves across different modes (e.g., view, edit, create).
|
||||
|
||||
### Data Representation
|
||||
|
||||
- A clear explanation of all fields displayed in the Detail View
|
||||
- Identification of:
|
||||
- Mandatory vs. optional fields
|
||||
- Read-only vs. editable fields
|
||||
- Derived or calculated values
|
||||
- Default values and formatting rules (dates, numbers, statuses, etc.)
|
||||
|
||||
### Modes and State Management
|
||||
|
||||
- Documentation must describe all supported screen modes (e.g., View, Edit, Create)
|
||||
- The behavior of the screen based on the `mode` input parameter must be explicitly defined
|
||||
- Transitions between modes (e.g., entering edit mode, canceling edits, saving changes) should be clearly documented
|
||||
|
||||
### Actions and User Interactions
|
||||
|
||||
A detailed list of all actions available within the Detail View, such as:
|
||||
|
||||
- Save, Edit, Cancel, Delete
|
||||
- Custom business actions
|
||||
|
||||
Expected behavior for each action, including:
|
||||
|
||||
- Validation rules
|
||||
- Confirmation dialogs
|
||||
- Success and error feedback
|
||||
|
||||
### Validation and Error Handling
|
||||
|
||||
- A comprehensive description of all validation rules applied to fields or sections
|
||||
- Clear explanation of how validation errors are presented to the user
|
||||
- Handling of backend or integration errors, including retry or recovery behavior
|
||||
|
||||
### Permissions and Access Control
|
||||
|
||||
Explicit definition of permissions affecting:
|
||||
|
||||
- Screen visibility and/or accessibility
|
||||
- Field visibility
|
||||
- Field editability
|
||||
- Available actions
|
||||
- Clarification on how permission changes impact the screen state and behavior
|
||||
|
||||
### Navigation and Context
|
||||
|
||||
- Description of how users reach the Detail View (e.g., from List View row selection)
|
||||
- Definition of back-navigation behavior and context preservation
|
||||
- Handling of unsaved changes when navigating away from the screen
|
||||
|
||||
### External System Mapping (If Applicable)
|
||||
|
||||
- Field-level mapping between the Detail View and external systems
|
||||
- Identification of source-of-truth fields
|
||||
- Synchronization behavior and timing (real-time vs. deferred)
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Specification",
|
||||
"position": 4
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Business Requirements Definition
|
||||
---
|
||||
|
||||
# Business Requirements Definition
|
||||
|
||||
The HOIST Business Analyst is responsible for drafting this section, outlining the solution scope in collaboration with the customer. This is the conceptual overview of what the HUB feature will accomplish. The customer is responsible for reviewing and approving the content to ensure it accurately reflects the original requirements.
|
||||
|
||||
During the specification sign-off process, the customer evaluates the documented scope and provides feedback as needed to ensure 100% alignment with business needs.
|
||||
|
||||
---
|
||||
|
||||
## Business Value
|
||||
|
||||
Describe the benefits and the business value — **not a proposed solution** — that can be achieved by improved system support. It is beneficial for the overall understanding if the benefits of the changed system support can be stated clearly.
|
||||
|
||||
---
|
||||
|
||||
## Current Process / Workflow
|
||||
|
||||
Describe the GAP in the IFS workflow or functionality that causes the need for this HUB feature.
|
||||
|
||||
### In IFS
|
||||
|
||||
Describe how it works in IFS:
|
||||
|
||||
- IFS Navigation (e.g., Sales / Quotation / Sales Quotation)
|
||||
- Reference an existing Work Instruction if available
|
||||
- If no WI exists, provide a brief description of how to navigate in IFS
|
||||
- Include IFS screenshots if needed
|
||||
|
||||
---
|
||||
|
||||
## Desired Outcomes & Desired Process / Workflow
|
||||
|
||||
Describe the desired behavior from the system and the resulting process/workflow.
|
||||
|
||||
---
|
||||
|
||||
## Business Requirements Details
|
||||
|
||||
This section focuses exclusively on detailing the business requirements. It should **not** include functional or technical requirements, as those will be addressed in subsequent sections.
|
||||
|
||||
The table below itemizes each requirement point in detail:
|
||||
|
||||
| Req. # | Description | Business Owner | Related Req. |
|
||||
|--------|-------------|----------------|--------------|
|
||||
| 1 | To associate a part master record with a customer | | 1 |
|
||||
| 2 | To run a report returning all parts belonging to a specific customer | | 1 |
|
||||
|
||||
---
|
||||
|
||||
## References, Sources, and Relations to Other Customizations
|
||||
|
||||
To support the requirements outlined in this specification, you may reference relevant documents, examples, or resources available on the project SharePoint site. Please ensure these references directly relate to the content.
|
||||
|
||||
:::caution
|
||||
If this specification was developed using a preliminary document from the customer, do **not** attach that document here — it may cause confusion.
|
||||
:::
|
||||
|
||||
| Ref. # | Title | Description | Type | Related Req. |
|
||||
|--------|-------|-------------|------|--------------|
|
||||
| 1 | | Document explaining the business requirements | document | |
|
||||
| 2 | | Report layout document | layout | |
|
||||
| 3 | CRIM 123 | There is a customization — here is the spec | spec | |
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Functional Design Definition
|
||||
---
|
||||
|
||||
# Functional Design Definition
|
||||
|
||||
This section, crafted by the Hoist Business Analyst in close partnership with the customer, provides a comprehensive guide to the solution. It outlines how the HUB feature will address the requirements specified in the Business Requirements section, ensuring all aspects are thoroughly covered.
|
||||
|
||||
To support developers — especially those unfamiliar with the relevant IFS functionality — this section includes:
|
||||
|
||||
- **Process Flow Diagram** done in Visio (e.g., Create Quote to Convert to Order). Start by reviewing the master flow diagram: *Mobile and IFS Flow on Hoist Hub* in SharePoint. Diagram needs to fit in an 8.5 x 11 Portrait format.
|
||||
- **Screens** — description, mock-ups, fields, buttons and actions, workflow
|
||||
- **Approvals** — approval logic if needed
|
||||
|
||||
The customer will review and approve this section during the sign-off process to confirm it aligns with their expectations.
|
||||
|
||||
---
|
||||
|
||||
## Screens
|
||||
|
||||
For each screen, document the following:
|
||||
|
||||
### Screen Description
|
||||
|
||||
Describe the purpose of the screen and the general use of it.
|
||||
|
||||
### Screen Mock-Ups
|
||||
|
||||
Visual representations of the user interface. Initially display wireframes done in Visio or Balsamiq. As screens are developed, take snapshots and annotate changes with Snagit.
|
||||
|
||||
### Fields
|
||||
|
||||
Fields in the table must be in the order they appear on the screen.
|
||||
|
||||
| Name | Characteristics | Notes |
|
||||
|------|----------------|-------|
|
||||
| Quotation No | View Only | Populated on Save to IFS |
|
||||
| Customer | Dropdown, Mandatory | Dropdown from IFS Customers |
|
||||
| Delivery Date | Enterable, Mandatory, Date Field | Date Picker |
|
||||
|
||||
**Characteristics legend:**
|
||||
- View Only
|
||||
- Enterable
|
||||
- Mandatory / Not Mandatory
|
||||
- Dollar, Date, Text, Dropdown
|
||||
|
||||
### Buttons and Actions
|
||||
|
||||
| Name | When Active | On Click Actions |
|
||||
|------|-------------|-----------------|
|
||||
| Save | Always | Save Quote Header to IFS; Return the Quotation No; Save Quote record to HUB |
|
||||
|
||||
### Workflow
|
||||
|
||||
Describe the workflow logic if needed:
|
||||
|
||||
- Sequential
|
||||
- Parallel Any
|
||||
- Parallel All
|
||||
|
||||
### Approvals
|
||||
|
||||
Describe the approval logic if needed.
|
||||
|
||||
---
|
||||
|
||||
## Permissions & Security
|
||||
|
||||
Use this section to define which HUB Profiles have which Permissions.
|
||||
|
||||
| HUB Profile | HUB Permissions | Notes |
|
||||
|-------------|----------------|-------|
|
||||
| External User | Can Create Quotes on HUB | |
|
||||
| External User | Can Delete Quotes on HUB | |
|
||||
| External User | Can Update Quotes on HUB | |
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Technical Design Definition
|
||||
---
|
||||
|
||||
# Technical Design Definition
|
||||
|
||||
This section is owned by the developer and should be updated with the solution as it was developed. The Hoist Business Analyst will be consulted as needed.
|
||||
|
||||
:::warning[Mandatory]
|
||||
This section is **mandatory** for all desired HUB Specs. All unused sections must be deleted.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## HUB Tables / Columns Mapping to IFS
|
||||
|
||||
List of HUB fields and their mapping into IFS fields:
|
||||
|
||||
| HUB Screen / Tab | HUB Label | HUB Table / Field Name | IFS Screen / Tab | IFS Label | IFS View / Field Name |
|
||||
|------------------|-----------|------------------------|------------------|-----------|----------------------|
|
||||
| Quote / Header | Quotation No | Quote / Quote_No | Sales Quotation / Header | Quotation No | Order_Quotation / Quotation_no |
|
||||
|
||||
---
|
||||
|
||||
## HUB to IFS API Calls
|
||||
|
||||
List of HUB Events that call IFS APIs:
|
||||
|
||||
| HUB Screen / Tab | HUB Button / Event | IFS API | Purpose |
|
||||
|------------------|-------------------|---------|---------|
|
||||
| Quote / Header | Save Button | Create_Quotation | To send the Quotation entered on HUB into IFS. API will return the Quotation No for saving on HUB |
|
||||
|
||||
---
|
||||
|
||||
## Report Layout
|
||||
|
||||
This section applies to both IFS Report Designer and Crystal Reports. IFS encourages customers to do their own layout modifications (as long as they're using Report Designer layouts).
|
||||
|
||||
Include an illustration or picture of the existing report or a data drawing of how it should look. Since a report can have multiple layouts, create a subsection within this section for each layout to be modified.
|
||||
|
||||
### `[REPORT_ID]` – `[REPORT_TITLE]`
|
||||
|
||||
#### Layout
|
||||
|
||||
`[layout_file_name.rdl]`
|
||||
|
||||
#### Description of Report Layout Properties
|
||||
|
||||
Document the following aspects where an exact match is required (e.g., for legal purposes, automatic processing):
|
||||
|
||||
- Paper size and orientation
|
||||
- Font (type, size, bold/italic/underline, etc.)
|
||||
- Position (e.g., 2cm from left margin, directly below line x)
|
||||
- Text alignment (left, right, centered, top, bottom)
|
||||
- Text wrapping or truncating
|
||||
- Date format
|
||||
- Number format (thousands and decimal separator, decimal places)
|
||||
- Conditional displaying
|
||||
- Graphics (e.g., company logo)
|
||||
- Calculations/formulas
|
||||
- Headers and footers
|
||||
- Page breaks
|
||||
- Special considerations for First Page, Repeat Section, and Last Page
|
||||
- Barcodes
|
||||
|
||||
#### Mockup of the Report Layout
|
||||
|
||||
Include a screenshot of a mockup of the intended report layout.
|
||||
|
||||
---
|
||||
|
||||
## Scheduled Task
|
||||
|
||||
### Purpose
|
||||
|
||||
Describe the purpose/need of the Scheduled Task.
|
||||
|
||||
### Description
|
||||
|
||||
Describe the Scheduled Task.
|
||||
|
||||
### Scheduled Task Setup
|
||||
|
||||
| Schedule name | Task Name | Schedule | Advanced |
|
||||
|---------------|-----------|----------|----------|
|
||||
| | Select from LOV | Daily / Weekly / Monthly / Scheduled / Interval / Custom + Time | e.g., language code or start and end date |
|
||||
|
||||
### Parameters
|
||||
|
||||
Define any special parameters to be used by the scheduled task.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Workflow Purpose
|
||||
|
||||
Describe the background/purpose for the Workflow.
|
||||
|
||||
### Workflow Description
|
||||
|
||||
Describe the objective(s) of the Workflow. Is it principally about Process Enrichment, User Interaction, or Data Validation?
|
||||
|
||||
### Workflow Key
|
||||
|
||||
Format should be CamelCase (e.g., `WorkTaskZoneCharge`).
|
||||
|
||||
### Workflow Description / Outcomes
|
||||
|
||||
Describe in non-technical terms what the Workflow should do. This can be a bulleted list or a flow chart if requirements are complex.
|
||||
|
||||
**Example:**
|
||||
> When a Service Work Task is Released, the workflow should:
|
||||
> - IF Site = 999 → do nothing
|
||||
> - ELSE → look up the service object on the task, then look up the service location for that object, then fetch the Location Type from the Scheduling tab on the Location; this location type ID will match a Non-Inventory Sales Part number; the workflow will add a Work Task Sales Line based on this Sales Part number with quantity 1; standard pricing rules apply to the sales line.
|
||||
|
||||
### Workflow Activation
|
||||
|
||||
Describe under what situations the Workflow should be triggered. Also indicate scenarios under which it should **not** be triggered.
|
||||
|
||||
**Projection Reactions vs. Custom Events:**
|
||||
|
||||
- Use **Projection Reactions** when the workflow should be triggered by a change on a specific page but not on other pages for the same database table.
|
||||
- Use **Custom Events** when the workflow should be triggered by database changes at a table level, regardless of which IFS Cloud Web page the user made the change on.
|
||||
|
||||
**Capturing different scenarios:**
|
||||
|
||||
Describe all scenarios that should lead to the workflow being triggered. Consider all creation paths: manual creation, adding to an existing request, from the Mobile Work Order app, from a Recurring Service Program (manually or by scheduled generation), etc.
|
||||
Reference in new issue
Block a user