IFS Projection
IFS Projection¶
The IFS Projection Delegate can be used to invoke CRUD (Create, Read, Update, and Delete) or Call actions on a projection.
The IFS Projection Delegate requires input for the projection details. This includes:
- Action (mandatory)- The CRUD or Call action to be performed
- Projection Name (mandatory)- The name of the projection
- 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 the returned Call value gets paired within the execution variables
- Parameters (optional) - The key and value pairs to be used with the projection action
- Nested Entity Parameters (optional) - The key and value pairs to be used with the projection action
- ETag Variable Name (mandatory for CRUD actions) - The name of the variable that the invoked projection's ETag will get carried around in. 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 projection selected ex: 'ProjectionName_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 errors messages are copied by checking 'Log Errors'. ex: 'ProjectionName_Error_Log'. When this parameter is specified, the underlying exception is assumed to be handled by the workflow and the transaction would continue normally.
- Read Collection (Optional) - By default projection read return only single record of data, but user has given the option to read a collection of data by enabling this option.
- Collection Variable Name - This is a text field which will be enabled upon enabling 'read collection' option. This variable will keep the value of returned collection which can be used within the BPA.
- Define a filter (Optional) - User has the ability to add filter criteria for the read operation. For instance user can select add filter criteria for different type 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 perform insert provided that there is no record to update in the database. There should be Projection 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 Projection Name, EntitySet Name, Nested Entity Name and Call Name options are populated from the server and can be selected from the dropdown. Once a Projection Name has been selected, the EntitySet, Nested Entities and Call options will contain the entity sets, nested entities and calls available for the corresponding projection.
The IFS Projection Delegate uses the execution variables for the projection action. Specific parameters can be added by clicking the ‘plus’ icon and specifying the key-value pair values to be used in the projection 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 projection that was invoked carries its ETag around in a variable called 'ETag'. In the projection delegate specifying an ETag variable name lets the projection invoked by the projection delegate 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 projection delegate is performing a CRUD action on the same row as the original CRUD action is being performed on. 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 Projection Delegate 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.
<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="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 projection 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 projection action is READ; it does not apply to any other action types.
To use this, set the projection 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 projection 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 projection 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 projection action is READ; it does not apply to any other type of action.
To use this, set the projection 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 projection 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="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>
Projection 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 user to read collection of data, where user need to enable read collection option and need to 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="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>
Filter Option¶
User can define a filter criteria for read values. The filter can be defined as a group of filter or a single one. By clicking on the filter button in properties panel can navigate to 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="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>
Order By Option¶
Users can define order by criteria for the values read via a projection delegate. 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="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 update operation where it perform insert provided that there is no record to update in the database. There should be Projection Read task with enabled "Log Errors" option prior to upsert enabled task. Refer below screen for upsert opration.
Below is the generated XML snippet for this Workflow.
<bpmn:extensionElements>
<camunda:inputOutput>
<camunda:inputParameter name="ifsBpaProjectionETagVariableName">ETag</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 Projection 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.