In Gateway, a filter is a mechanism for deciding what to load in a Load step. For example, in the Project Data flow, a filter would determine what projects to transfer from the source to the destination. You can think of a filter as a special type of parameter. Filters are defined in a provider XML file and referenced in a load step via the LoadContext interface.
How Is Filter Defined
A filter is defined in a provider XML file much like normal parameters, except it has its own element tags for defining the structure of the filter. The following snippet from the SampleProvider.xml of the sample project illustrates how to define a filter:
<Parameter>
<DefaultValue>Project:ImportProjectIds=E-1922,E-1833</DefaultValue>
<Description>A comma separated list of project Ids</Description>
<FilterOptions>
<ObjectOptions>
<ObjectName>Project</ObjectName>
<Field>
<Name>ImportProjectIds</Name>
<DefaultValue>Comma Separated IDs</DefaultValue>
</Field>
</ObjectOptions>
</FilterOptions>
<Name>ERPProjectFilter</Name>
<Sequence>2</Sequence>
<Title>ERP Project Filter</Title>
<Type>Filter</Type>
</Parameter
As illustrated in the snippet above, the filter is defined by specifying a Parameter element that includes a Type element with a value of Filter. Additionally, the FilterOptions element defines the structure of the filter. There should be one ObjectOptions element for each object involved. Finally, the Field element includes elements that define the field name and a default value. There can be more than one Field element for each object.
Since a filter is just a parameter that has a data type of Filter, you can set its default value and attributes in much the same manner as these aspects are set for other parameters. When you create business flows in Primavera Gateway, you can set the default value of a filter and determine whether the filter is hidden, optional, required, or read only when the business flow is used in a synchronization. If you set the filter to hidden or read only, the value that you set for the filter can not be changed when the business flow is used in a synchronization. If you set the filter to optional or required, the value of the filter can be changed when the flow is used in a synchronization.
Setting Filters in Primavera Gateway
Follow the steps below to set the default value of a filter and determine whether the default value can be changed in the synchronization:
- Log into Primavera Gateway with a user the has an Admin role.
- Select Flow Type and choose a business flow type.
- Select the Business Flows tab.
- Select Add to create a new business flow or highlight an existing business flow and select Edit.
- In the General tab, specify or change the information and click Next.
- In the Mappings tab, click Next.
- In the Parameters tab, choose a parameter that has a filter.
Note: Filters are parameters that have a data type of Filter.
- Build your criteria for the filter by adding and deleting rows.
- In the Attribute column, depending on how you want the filter to be accessed, select Hidden, Optional, Required, or Read only.
- Click Save.
Changing the Default Value of Filters
When you specify the attribute of a filter as optional or required in the business flow, you can override the default value when the business flow is used in a synchronization. Follow the steps below to override the default value of a filter.
- Log into Primavera Gateway.
- Select Synchronizations.
- Select Add to create a new synchronization or highlight an existing synchronization and select Edit.
- In the Flow & Deployments tab, specify or change the information and click Next.
- In the Parameters tab, change your criteria for the filter by adding and deleting rows. and click Next.
Note: Only filters that have been set as optional or required, or read only are displayed in this tab.
- In the Review & Submit tab, click Save.
How to Refer to a Filter in the Provider Code
A filter can be referenced in a provider by calling the getParameter method from the FlowContext interface. Here is an example from SampleProvider.java of the sample provider project.
private static List<ChildFlowInfo> getChildFlowInfo(FlowContext context) throws ProviderException {
@SuppressWarnings("unchecked")
List<FilterValue> filters = (List<FilterValue>) context.getParameter("ERPProjectFilter");
if ((filters == null) || (filters.size() == 0)) {
return null;
}
String projectIds = null;
for (FilterValue fv : filters) {
String objectName = fv.getObjectName();
// get Project specific filter information
if ("Project".equals(objectName)) {
if ("ImportProjectIds".equals(fv.getFieldName())) {
projectIds = fv.getValue();
break;
}
}
}
String[] projIds = projectIds.split(",");
List<ChildFlowInfo> childInfoList = new ArrayList<ChildFlowInfo>();
for (String id : projIds) {
ChildFlowInfo childInfo1 = new ChildFlowInfo();
childInfo1.setParameter("ImportProjectId", id);
childInfoList.add(childInfo1);
}
return childInfoList;
}
You can see that the filter is retrieved by calling FlowContext.getParameter, and cast into a list of FilterValue. Each FilterValue is like a clause, which contains information like
object.field = some value
The net result of the filter is AND of all the clauses.
In this example, only Project object and ImportProjectIds field are defined. ImportProjectIds is simply a comma separated project ids. Each project id will be saved to the hidden ImportProjectId parameter, and a separate job will be spun off for synchronizing each project.