--- sidebar_position: 1 title: IFS Integration Architecture --- # Integration with IFS :::danger Documentation versioning with git ::: 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. |