Geo Permissions on Models

If you need to assign permissions based on physical location, you can setup Geographic Permissions on your models. One common example is allowing a role to see only those sites located in its own geographic region. Another example is allowing a role to see shipments being routed from a certain region to another certain region.

Address and ModelLink fields on a model can be defined as contributors to geo-permissions. (A model link field can only be a geo-permission contributor if the model-level type is Site or PartnerSite.)

Each field can be selected as FROM, TO or IN contributor. For FROM and TO, these will be required to match the ends of a GeoLanePermission associated with the current role. For IN, these will be required to match a GeoPermission associated with the current role.

You need to follow a few steps to make Geo Permissions to work correctly. The first section below explains how to setup Geo Permissions meta-data on a model and how to assign role types to use geo-permissions on this model. The second section explains how to create all required Geo model instances in the database to give the role instances permissions.

Procedure 4.4. To enable Geo Permissions on a model

1. Open a .model or .mdf file in model/mdf editor

2. Select any address and/or model link fields as Geo Permission contributors

   Figure 4.3. Geo Permission type can be selected from the drop-down combo box in the Address field details section.

   Figure 4.4. Geo Permission type can be selected from the drop-down combo box in the ModelLink field details section.

   Please note that ModelLink field's model-level type must be Site or PartnerSite in order to be Geo Permission contributor.

3. After selecting one or more field as Geo Permission contributors, you should open and assign geo-permissions to desired role types.

   Figure 4.5. Simply checking "By Geo" check box assigns Geo Permissions on the role type.

Procedure 4.5. How to create Geo models for a role type.

1. In order to give a specific role geo-permissions, we need to start by creating GeoPatternList models. GeoPatternList is a name for a collection of one or many GeoPattern models. Below is an example code part that creates a GeoPatternList with the name "Texas". This GeoPatternList can cover cities, sites and partner sites within Texas.

   GeoPatternList geoPatternList = new GeoPatternList();

   geoPatternList.setEnterpriseName(ENT_NAME);

   geoPatternList.setOrganizationName(ORG_NAME);

   geoPatternList.setValueChainId(VALUE_CHAIN_ID);

   geoPatternList.setName("Texas");

2. Now you need to create GeoPattern models for GeoPatternList(Texas).
   

   GeoPattern geoPattern = new GeoPattern();

   geoPattern.setValueChainId(VALUE_CHAIN_ID);

   geoPattern.setGeoPatternListName("Texas");

   geoPattern.setGeoPatternListOrganizationName(ORG_NAME);

   geoPattern.setGeoPatternListEnterpriseName(ENT_NAME);

   geoPattern.setGeoPatternType(GeoPatternType.ADDR_COMP_2.getValue());

   geoPattern.setAddressComponent2("Dallas");

   geoPattern.setAddressCountry("US");

   GeoPattern geoPattern2 = new GeoPattern();

   geoPattern2.setValueChainId(VALUE_CHAIN_ID);

   geoPattern2.setGeoPatternListName("Texas");

   geoPattern2.setGeoPatternListOrganizationName(ORG_NAME);

   geoPattern2.setGeoPatternListEnterpriseName(ENT_NAME);

   geoPattern2.setGeoPatternType(GeoPatternType.SITE.getValue());

   geoPattern2.setEnterpriseName(ENT_NAME);

   geoPattern2.setOrganizationName(ORG_NAME);

   geoPattern2.setSiteName("Fort Worth");

   You can add as many patterns as you want to a list. However, GeoPatternType should be defined while adding a pattern. Supported GeoPattern types are:

   • GeoPatternType.COUNTRY

   • GeoPatternType.ADDR_COMP_1(State)

   • GeoPatternType.ADDR_COMP_2(City)

   • GeoPatternType.PARTNER_SITE

   • GeoPatternType.SITE

   Please also note that depending on the GeoPatternType you choose, you should provide the required information.

3. In order to provide from-to relationship, you need to create GeoLanePattern models. GeoLanePattern model has two fields: fromGeoPatternList and toGeoPatternList. These two fields are references to two GeoPatternLists which define geographic regions

   GeoLanePattern geoLanePattern = new GeoLanePattern();

   geoLanePattern.setName("Texas-To-Louisiana");

   geoLanePattern.setFromGeoPatternListEnterpriseName(ENT_NAME);

   geoLanePattern.setFromGeoPatternListName("Texas");

   geoLanePattern.setFromGeoPatternListOrganizationName(ORG_NAME);

   geoLanePattern.setToGeoPatternListEnterpriseName(ENT_NAME);

   geoLanePattern.setToGeoPatternListName("Louisiana");

   geoLanePattern.setToGeoPatternListOrganizationName(ORG_NAME);

   geoLanePattern.setGeoLanePatternEnterpriseName(ENT_NAME);

   geoLanePattern.setGeoLanePatternOrganizationName(ORG_NAME);

4. GeoPermission and GeoLanePermission models map role types to GeoPatternLists. GeoPermission defines "IN" relationship while GeoLanePermission defines "FROM-TO" relationship. If the target model has a Site model link with "IN" GeoPermType set then you need to create GeoPermission record which points to a GeoPatternList which includes GeoPattern records of "GeoPatternType.SITE" types.
   

   GeoPermission geoPermission = new GeoPermission();

   geoPermission.setGeoPatternListName("Texas");

   geoPermission.setGeoPatternListEnterpriseName(ENT_NAME);

   geoPermission.setGeoPatternListOrganizationName(ORG_NAME);

   geoPermission.setRoleEnterpriseName(userContext.getRoleEnterpriseName());

   geoPermission.setRoleName(userContext.getRoleName());

   geoPermission.setRoleOrganizationName(ORG_NAME);

   geoPermission.setRoleSiteName(userContext.getRoleSiteName());

   geoPermission.setValueChainId(VALUE_CHAIN_ID);

   
   If the target model has a PartnerSite field with "FROM" and another PartnerSite field with "TO" GeoPermTypes set, then you need to create GeoLanePermission where from and to GeoPatternLists contain "GeoPatternType.PARTNER_SITE" type GeoPattern models.
   
   

   GeoLanePermission geoLanePermission = new GeoLanePermission();

   geoLanePermission.setEnterpriseName(ENT_NAME);

   geoLanePermission.setOrganizationName(ORG_NAME);

   geoLanePermission.setGeoLanePatternEnterpriseName(ENT_NAME);

   geoLanePermission.setGeoLanePatternName("Texas-to-NewYork");

   geoLanePermission.setGeoLanePatternOrganizationName(ORG_NAME);

   geoLanePermission.setRoleName(userContext.getRoleName());

   geoLanePermission.setRoleOrganizationName(userContext.getRoleOrganizationName());

   geoLanePermission.setRoleSiteEnterpriseName(userContext.getRoleEnterpriseName());

   geoLanePermission.setRoleSiteName(userContext.getRoleSiteName());

   geoLanePermission.setSysSiteOrganizationId(userContext.getRoleOrganizationId(), true);

   geoLanePermission.setValueChainId(VALUE_CHAIN_ID);