IFS API

IFS API¶

The IFS API (previously known as IFS Projection) can be used to invoke CRUD (Create, Read, Update, and Delete) or Call actions on an API.

The IFS API Task requires input for the API details. This includes:

Action (mandatory)- The CRUD or Call action to be performed
API Name (mandatory)- The name of the API. The API's shown here are Standard APIs and active Entity Service APIs. Inactive Entity Service APIs are not listed here. If required to list Entity Service API, it has to be activated first via the API Explorer page.
EntitySet Name (mandatory for CRUD actions) - The name of the Entity Set
Nested Entity Name (optional) - The name of the nested entity
Call Name (mandatory for Call actions) - The signature of the Call
Call Return Value Name (optional) - The key of the returned Call value gets paired with the execution variables
Parameters (optional) - The key and value pairs to be used with the API action
Nested Entity Parameters (optional) - The key and value pairs to be used with the API action
ETag Variable Name (mandatory for CRUD actions) - The name of the variable that the invoked API's ETag will get carried around in. The user has the ability to override the ETag variable by checking 'Override ETag', where the ETag variable name will be replaced with the name of the API selected ex: 'APIName_ETag', else if un-checked the variable name will have defaulted to 'ETag'. More information can be found in Managing the ETag Variable.
Error Log Variable Name (optional) - User has the ability to specify the name of the execution variable into which error messages are copied by checking 'Log Errors'. ex: 'APIName_Error_Log'. When this parameter is specified, the underlying exception is assumed to be handled by the workflow and the transaction will continue normally. This variable will be available in the execution when an error is detected.
Read Collection (Optional) - By default API read returns only a single record of data, but the user has been given the option to read a collection of data by enabling this option.
Collection Variable Name - This is a text field that will be enabled upon enabling the 'read collection' option. This variable will keep the value of returned collection which can be used within the BPA.
Define a filter (Optional) - The user has the ability to add filter criteria for the read operation. For instance, the user can select add filter criteria for different types of attributes (eg : age >= 18 AND age < 60). The criteria is specified using the form described below.
Define an order by criteria (Optional) - The user can add order by criteria for the read operation. For instance, the user can select add order by criteria for different types of attributes (eg: Id asc, CustomerNo desc, Price asc). The criteria is specified using the form described below.
Enable Upsert (Optional) - User can select this option in update operation where it performs insert provided that there is no record to update in the database. There should be API Read task with enabled "Log Errors" option prior to upsert enabled task.
Only Explicit Parameters (Optional) - User can select this option in CREATE operation when only the parameters explicitly given are to be taken as the payload. This option will be unticked by default. When unticked, any variable in the execution can be taken as the payload.

The API Name, EntitySet Name, Nested Entity Name and Call Name options are populated from the server and can be selected from the dropdown. Once an API Name has been selected, the EntitySet, Nested Entities and Call options will contain the entity sets, nested entities and calls available for the corresponding API.

The IFS API task uses the execution variables for the API action. Specific parameters can be added by clicking the ‘plus’ icon and specifying the key-value pair values to be used in the API action.

An ETag is used to determine if a row has been changed since it was last accessed before invoking an action on it. The original API that was invoked carries its ETag around in a variable called 'ETag'. In the IFS API task specifying an ETag variable name lets the API invoked by the IFS API task carry its ETag around in a different variable so it doesn't overwrite the original ETag. Do not override the ETag as the default variable name will be set to 'ETag', if the IFS API Task is performing a CRUD action on the same row as the original CRUD action is being performed. Refer Managing the Etag Variable section for more details about Etag variable.

Example of a Read action selected:

Example of a Call action selected:

Below is the generated XML for the first IFS API Task example above where a Create action is selected. In the case of a Call action being selected the XML would be the same except the ifsBpaProjectionEntitySetName parameter would be replaced with a ifsBpaProjectionCallSignature parameter.

ifsBpaProjectionType is a hidden variable which carrying the API type and require it for backend side implementation to be done based on different types. For an example, if selected API is a standard API then value is "Standard" while selected API is an Entity Service API then value is "DES".

    <bpmn:serviceTask id="Activity_1tj9cd6" name="Projection Insert" camunda:class="com.ifsworld.fnd.bpa.IfsProjectionDelegate">
      <bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionType">Standard</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionAction">CREATE</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionName">StatesHandling</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionParameters">
            <camunda:map />
          </camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionEntitySetName">Reference_StateCodes</camunda:inputParameter>
        </camunda:inputOutput>
      </bpmn:extensionElements>
      <bpmn:incoming>Flow_1lmd3oo</bpmn:incoming>
      <bpmn:outgoing>Flow_1bbg3gz</bpmn:outgoing>
    </bpmn:serviceTask>

Select Option¶

A select functionality is available when the API action is READ. This works by using the provided parameter to select only the columns that is specified from the results. Note that this functionality only works when API action is READ; it does not apply to any other action types.

To use this, set the API action to READ and add a key-value pair to the parameters with a key of $select. The value is the select columns of the entity (multiple columns can provide with comma separation). For example, in the following figure, the API read will return only the CountryCode and StateCode columns as the result.

Below is the generated XML snippet for this Workflow.

<bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionType">Standard</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionAction">READ</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionName">StatesHandling</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionParameters">
            <camunda:map>
              <camunda:entry key="$select">CountryCode,StateCode</camunda:entry>
            </camunda:map>
          </camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionEntitySetName">Reference_StateCodes</camunda:inputParameter>
        </camunda:inputOutput>
</bpmn:extensionElements>

Skip Option¶

A skip row functionality is available when the API action is READ. This works by using the provided parameters to filter the rows, skip the specified number of rows from the query result, and return the next row. Note that this functionality only works when API action is READ; it does not apply to any other type of action.

To use this, set the API action to READ and add a key-value pair to the parameters with a key of $skip. The value is the number of rows to skip. For example, in the following figure, the API read will skip the first 3 rows and return the fourth row.

Below is the generated XML snippet for this Workflow.

<bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionType">Standard</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionAction">READ</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionName">StatesHandling</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionParameters">
            <camunda:map>
              <camunda:entry key="$skip">3</camunda:entry>
            </camunda:map>
          </camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionEntitySetName">Reference_StateCodes</camunda:inputParameter>
        </camunda:inputOutput>
</bpmn:extensionElements>

Error Handling¶

This will allow the users to handle errors directly within the Workflow rather than having the transaction rolled back. If the Log Errors checkbox is clicked, the underlying exception will be logged into the specified variable and the transaction will continue normally.

Read Collection¶

This will allow the user to read a collection of data, where the user needs to enable the read collection option and provide a variable name to store the collection.

Below is the generated XML snippet for this Workflow.

<bpmn:serviceTask id="Activity_184rql5" name="Read RB Bodies" camunda:class="com.ifsworld.fnd.bpa.IfsProjectionDelegate">
      <bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaProjectionAction">READ</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionType">Standard</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionIsCollection">true</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionCollectionVariableName">RegulatoryBodySet_Set</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionErrorLogVariableName">RegulatoryBodyHandling_Error_Log</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionIsErrorLog"></camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionName">RegulatoryBodyHandling</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionEntitySetName">RegulatoryBodySet</camunda:inputParameter>
        </camunda:inputOutput>
      </bpmn:extensionElements>      
    </bpmn:serviceTask>

User can define filter criteria for read values. The filter can be defined as a group of filters or a single one. By clicking on the filter button in the properties panel can navigate to the following filter window.

Below is the generated XML snippet for this Workflow.

<bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaProjectionAction">READ</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionType">Standard</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionIsCollection">true</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionCollectionVariableName">EnterpAddressCountrySet_Set</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionErrorLogVariableName">StatesHandling_Error_Log</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionIsErrorLog"></camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionName">StatesHandling</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionEntitySetName">EnterpAddressCountrySet</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaFilterQuery">(country_code LIKE '%CA%' AND validate_state_code = 'BC')</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaJsonFormatTreeQuery">{"errors":[],"logic":{"and":[{"and":[{"in":["CA",{"var":"country_code"}]},{"==":[{"var":"validate_state_code"},"BC"]}]}]},"data":{"country_code":null,"validate_state_code":null}}</camunda:inputParameter>
        </camunda:inputOutput>
      </bpmn:extensionElements>

Note:

The Query Builder filter tool supports expression language for String type parameters within the tool. However, it is important to note that this feature is not available for parameters with other data types, such as Date, Number, Boolean, Timestamp, Enum, etc. The reason for this is to avoid introducing unnecessary complexity that could potentially impair the user experience. Nevertheless, users have the option to edit the filter text field and modify the parameters to use expression language as needed.

As an example

Data Types	Expression Language Format
Number types	< number_attribute > = ${number}
For other types (String, Enumeration, Date, Boolean, Timestamp, etc.)	< attribute > = '${variable}'

Order By Option¶

Users can define order by criteria for the values read via an IFS API task. By clicking on the order by button in the properties panel can navigate to the following filter window.

Control	Usage
	- The results will be sorted in ascending order by the specified attribute. - The results will be sorted in descending order by the specified attribute.
	- The control is used to move the selected attribute downwards in the list. - The control is used to move the selected attributed upwards in the list.

NOTE: The order by widget supports the drag and drop feature for the following.

Drag and drop items between the left & right columns.
Drag and drop items within the right column.

Below is the generated XML snippet for this Workflow.

<bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaProjectionAction">READ</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionType">Standard</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionName">BpaTestHandling</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionEntitySetName">BpaTestEntitySet</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaOrderByQuery">NullValue desc,TestEnum asc,StringValue asc</camunda:inputParameter>
        </camunda:inputOutput>
</bpmn:extensionElements>

Upsert Option¶

User can select this option in the update operation where it performs insert provided that there is no record to update in the database. There should be an IFS API Read task with an enabled "Log Errors" option prior to the upsert enabled task. Refer to below screen for upsert operation.

Below is the generated XML snippet for this Workflow.

<bpmn:extensionElements>
        <camunda:inputOutput>
          <camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionType">Standard</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionAction">UPDATE</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionIsUpsert">true</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionName">RegulatoryBodyHandling</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionEntitySetName">RegulatoryBodySet</camunda:inputParameter>
          <camunda:inputParameter name="ifsBpaProjectionParameters">
            <camunda:map>
              <camunda:entry key="RegulatoryBodyCode">A1</camunda:entry>
            </camunda:map>
          </camunda:inputParameter>
        </camunda:inputOutput>
      </bpmn:extensionElements>

Managing the ETag Variable¶

The goal of the above Workflow is to update the Sub Project and the Project Description based on the status of the Project read (i.e., if the status of the Project is ‘initialized’ the update happens).

Event action is configured to trigger the Workflow when there is a change in the Manager to whom the project is assigned.

1.Sub Project record is read using the Project Id available in the execution flow. At this point, we need to override the ETag variable (i.e. SubProjectsHandling_ETag), because the registered event action provides an ETag value with the same variable name that we’ll need in step 3. So, this is where we need to manage our ETag variables to perform two updates.

Below depicts the IFS API Property,

2.If the condition is satisfied (i.e., if the status of the Project is ‘initialized’), the Workflow proceeds to update the Sub Project Description. We need to make sure that override ETag is enabled in this task (i.e.SubProjectsHandling_ETag) because we are going to update the same record that was read in task 01 (the ETag value was stored in the SubProjectsHandling_ETag variable). If we don’t override the ETag variable in both the update tasks, the request will fail with the ‘Etag is incorrect’ error because there is a mismatch between the ETag value provided and the one stored in Oracle. The projection validates the incoming ETag value before updating the Sub Project Description, to ensure that the record hasn’t changed since reading the values in task 1. If the record has changed the update of the Sub Project Description is aborted.

3.The last task updates the parent record, using the ETag value provided from the event at the start of the workflow. Consequently, the ETag variable in task 3 does not need to be overridden.

Download BPA Here

Validations¶

There are deployment time validations for the IFS API task. please refer the IFS API Task section in deployment validation page for more details.

It is not allowed to deactivate Entity Service API via API Explore page, if it is used by any active Workflows. A validation is performed when deactivating an Entity Service API to ensure that there are no active Workflows associated with the API being deactivated.

IFS API

IFS API¶

Select Option¶

Skip Option¶

Error Handling¶

Read Collection¶

Filter Option¶

Order By Option¶

Upsert Option¶

Managing the ETag Variable¶

Validations¶