Files
wiki-hoist/docs/hoist-hub/ifs-integration.md
T
jaime.meza d1251a5f05 docs: replace default README and clean up minor doc issues
Replace boilerplate Docusaurus README with project-specific content
covering the actual stack (pnpm), Diátaxis structure, and docs layout.
Also remove a stray danger admonition from ifs-integration.md and fix
logo filename reference in docusaurus.config.ts.
2026-06-22 08:16:54 -05:00

6.1 KiB

sidebar_position, title
sidebar_position title
1 IFS Integration Architecture

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
Parameters I

Example:

GetCaseById Gets a case from IFS by KeyRef
CaseId - Mandatory In
IfsSettings - Mandatory In
CcCase Out

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.