Pankaj

Spectrum™ Technology Platform Version 9.0 Administration Guide Contents Chapter 1: Getting Started..................................................................................7 Starting and Stopping the Server........................................................................8 Installing the Client Tools.....................................................................................8 Starting the Client Tools.......................................................................................9 A First Look at Management Console.................................................................9 Configuring a New System.................................................................................11 Chapter 2: Managing Security..........................................................................13 Security Model.....................................................................................................14 Users.....................................................................................................................15 Creating a User..........................................................................................15 Modifying a User.........................................................................................15 Disabling a User Account...........................................................................16 Deleting a User...........................................................................................16 Roles.....................................................................................................................16 Creating a Role...........................................................................................17 Secured Entity Types - Platform.................................................................18 Secured Entity Types - Advanced Matching Module..................................19 Secured Entity Types - Business Steward Module.....................................20 Secured Entity Types - Data Hub Module..................................................20 Secured Entity Types - Data Normalization Module...................................21 Secured Entity Types - Enterprise Data Integration Module......................21 Secured Entity Types - Location Intelligence Module.................................21 Secured Entity Types - Database Resources.............................................21 Secured Entity Overrides...................................................................................21 Creating a Secured Entity Override............................................................22 Viewing a Secured Entity Override.............................................................23 Security for the Location Intelligence Module..................................................23 Example: Overriding Permissions at the Role Level..................................25 Example: Overriding Permissions at the User Level..................................28 Creating a Named Resources Administrator..............................................30 Creating a Spatial Dataflow Designer.........................................................31 Turning off Security for Services and the Repository.................................32 Disabling Platform Security Versus Turning Off Spatial Security...............33 Disabling User Security......................................................................................33 Limiting Server Directory Access......................................................................33 Configuring HTTPS Communication.................................................................35 Chapter 3: Configuring Database Resources.................................................37 Introduction to Database Resources.................................................................38 Adding a Database Resource.............................................................................38 Adding an Enterprise Geocoding Module Global Database Resource......38 Adding an Enterprise Geocoding Module U.S. Database Resource..........39 Adding an Enterprise Geocoding Module AUS or GBR Database Resource....................................................................................................40 Adding an Enterprise Routing Module Database Resource.......................41 Adding an Enterprise Tax Module Database Resource..............................42 Adding a Location Intelligence Module Centrus Database Resource........42 Adding a Location Intelligence Module Database Named Connection......43 Adding a Location Intelligence Module Named Table Resource................44 Adding a Universal Addressing Module Database Resource.....................46 Adding a Universal Addressing Module Global Database Resource.........46 Optimizing Database Resources.......................................................................48 Deleting a Database Resource...........................................................................49 Chapter 4: Configuring Resources..................................................................51 Introduction to Resources..................................................................................52 Databases............................................................................................................52 Adding or Modifying a Database Connection.............................................52 Deleting a Database Connection................................................................52 JDBC Drivers..............................................................................................53 Supported Database Data Types...............................................................54 File Servers..........................................................................................................55 Connecting to an FTP File Server..............................................................55 Connecting to a Hadoop Distributed File System.......................................55 Modifying a File Server...............................................................................57 Deleting a File Server.................................................................................57 External Web Services........................................................................................57 Adding a SOAP Web Service.....................................................................58 Adding a REST Web Service.....................................................................60 Renaming an External Web Service...........................................................61 Deleting an External Web Service..............................................................61 Using a Windows Mapped Drive........................................................................62 Chapter 5: Managing Execution.......................................................................65 Services................................................................................................................66 Specifying Default Service Options............................................................66 Previewing a Service..................................................................................66 Limiting the Number of Records to Process...............................................67 4 Spectrum™ Technology Platform 9.0 Specifying a Field Separator......................................................................67 Setting Service Timeout..............................................................................68 Optimizing Services....................................................................................68 Jobs and Process Flows....................................................................................68 Scheduling Jobs and Process Flows..........................................................68 Using a File Monitor to Trigger a Job or Process Flow...............................70 Viewing Execution Status and History........................................................71 Pausing and Resuming a Job.....................................................................73 Canceling a Job or Process Flow...............................................................73 Exporting Execution History.......................................................................73 Setting the Default Malformed Records Threshold....................................74 Setting Default Report Options...................................................................74 Transaction History.............................................................................................74 Viewing Transaction History.......................................................................75 Setting Transaction History Options...........................................................75 Remote Servers...................................................................................................75 Adding a Remote Server............................................................................75 Routing a Service to a Remote Server.......................................................76 Modifying a Remote Server........................................................................77 Deleting a Remote Server..........................................................................77 Troubleshooting Remote Server Errors......................................................77 Optimizing Sort Performance.............................................................................78 Setting Default Type Conversion Options........................................................79 Date and Time Patterns..............................................................................80 Number Patterns........................................................................................82 Configuring Remote Component Options........................................................84 JVM Performance Tuning...................................................................................85 Chapter 6: Monitoring Your System................................................................87 Monitoring Performance.....................................................................................88 Configuring E-mail Notification.........................................................................89 Configuring License Expiration Notification....................................................89 Event Log.............................................................................................................90 Viewing the Event Log................................................................................90 Setting Event Log Options..........................................................................90 Viewing Version Information..............................................................................91 Viewing and Exporting License Information....................................................91 Chapter 7: About Spectrum Technology Platform.........................................93 What Is Spectrum™ Technology Platform?......................................................94 Enterprise Data Management Architecture.......................................................95 Spectrum™ Technology Platform Architecture................................................98 Modules and Components...............................................................................101 Administration Guide 5 Appendix..........................................................................................................105 Appendix A: Country ISO Codes and Module Support.....................107 Country ISO Codes and Module Support.................................................108 6 Spectrum™ Technology Platform 9.0 Getting Started In this section: • • • • • Starting and Stopping the Server . . . . . . . . . . . . . . . . . . . .8 Installing the Client Tools . . . . . . . . . . . . . . . . . . . . . . . . . .8 Starting the Client Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 A First Look at Management Console . . . . . . . . . . . . . . . . .9 Configuring a New System . . . . . . . . . . . . . . . . . . . . . . . .11 1 Starting and Stopping the Server Starting and Stopping the Server You may need to stop and start the Spectrum™ Technology Platform server to perform maintenance such as installing a lookup table or applying a product update. • On Windows, Spectrum™ Technology Platform is set to start automatically when Windows starts up. To ensure that Spectrum™ Technology Platform has started, right click on the Spectrum™ Technology Platform icon in the Windows system tray. The Start Server menu item should be grayed out. To stop Spectrum™ Technology Platform, select Stop Server • To start or stop the server on Unix or Linux: a) Change the working directory to the bin directory of where Spectrum™ Technology Platform is installed. For example, cd /usr/g1/tst/server/bin b) Source the setup file. For example, . ./setup c) Launch Spectrum™ Technology Platform. • To launch Spectrum™ Technology Platform in the background, type the following command: ./server.start • To launch Spectrum™ Technology Platform in the foreground, type the following command: ./server.start console Note: To stop Spectrum™ Technology Platform, type the following command: ./server.stop Installing the Client Tools The Spectrum™ Technology Platform client tools are Windows applications that you use to administer your server and design and run dataflows and process flows. You must install your Spectrum™ Technology Platform server before installing the client tools. Before installing, be sure to read the release notes. The release notes contains important compatibility information as well as release-specific installation notes. This procedure describes how to install the following client tools: • Enterprise Designer— Use Enterprise Designer to create, modify, and run dataflows. • Management Console—Use the Management Console to perform administrative tasks such as setting service defaults, scheduling jobs, managing users and security, and so on. • Interactive Driver—Use Interactive Driver to test different processing settings. Interactive Driver allows you to run a small number of records through a process to preview the result. • Job Executor—Job Executor is a command line tool that allows you to run a job from a command line or script. The job must have been previously created and saved on Spectrum™ Technology Platform using Enterprise Designer. • Process Flow Executor—Process Flow Executor is a command line tool that allows the execution of a process flow from a command line or script. The process flow must have been previously created and saved on Spectrum™ Technology Platform using Enterprise Designer. To install the client tools: 1. Open a web browser and go to the Spectrum™ Technology Platform Welcome Page at: http://: 8 Spectrum™ Technology Platform 9.0 Chapter 1: Getting Started For example, if you installed Spectrum™ Technology Platform on a computer named "myspectrumplatform" and it is using the default HTTP port 8080, you would go to: http://myspectrumplatform:8080 2. Click Platform Client Tools. Starting the Client Tools The client tools (Enterprise Designer, Management Console, or Interactive Driver) are Windows applications that you launch from the Start menu. They are easy to launch but there are a few things to keep in mind. To start a Spectrum™ Technology Platform client: 1. Select Start > Programs > Pitney Bowes > Spectrum™ Technology Platform > Client Tools. 2. Select the client you wish to start (Management Console, Enterprise Designer, or Interactive Driver). 3. Type in the server name or select it from the drop-down list. Note: If you have multiple instances of the Management Console accessing the same Spectrum™ Technology Platform server, it is possible for one user to overwrite another user's changes. Therefore, it is recommended that you do not run multiple instances of the Management Console against the same server. 4. Enter your user name and password. 5. In the Port field, enter the network port that the server has been configured to use for Spectrum™ Technology Platform communication. The default port number is 8080. 6. Click Use secure connection if you want communication between the client and the server to take place over an HTTPS connection. Note: A secure connection is only available if HTTPS communication has been configured on the server. 7. Click Login. A First Look at Management Console Management Console is the tool for administering your Spectrum™ Technology Platform system. This topic provides an overview of the Management Console. Using Management Console, you can perform such tasks as: • • • • Manage users and other security options Define connections to data sources such as databases or web services Specify default settings for services Schedule job execution The figure below shows Management Console. Administration Guide 9 A First Look at Management Console Figure 1: Management Console The nodes in the left pane provide access to the Management Console functions. The nodes are: 10 Modules This node lists the modules you have installed on your system that have services or administrative tools. Note that not all modules appear in Management Console because some modules do not come with services or administrative tools. For modules that come with predefined services, you can set the default processing options for the services here. You can also define the reference databases to use with the module, such as postal reference data or geocoding reference data, if applicable. Execution This node contains options that control the running of dataflows and services, including the scheduling of batch jobs, job logs, and data type conversion options. Resources This node contains options for defining connections to the data that you want to process through Spectrum™ Technology Platform. In order for a dataflow designer to be able to create a dataflow that either reads from or writes to a resource, you must define that resource here. System This node contains options that can assist you in managing your system, including email notification options, licensing information, and remote server configuration. Event Log This node contains options for logging service errors, and also displays the event log for the services on your system. Security This node contains the options for managing users. Transaction History This node contains options for usage reports. Spectrum™ Technology Platform 9.0 Chapter 1: Getting Started Configuring a New System When you first install Spectrum™ Technology Platform there area few things you should do first as an administrator before you start using the system to ensure that your system has a basic level of security as well as access to the data you want to process through Spectrum™ Technology Platform. 1. Change the password for the admin user. a) Select Start > Programs > Pitney Bowes > Spectrum™ Technology Platform > Client Tools > Management Console. b) Under the Security node, click Users. c) Select admin then click Modify. d) In the Password field, enter a new password. Enter it again in the Confirm password field. e) Click OK. 2. Create users and roles as needed. For more information, see Creating a User on page 15. 3. Specify which folders on the Spectrum™ Technology Platform server you want to allow users to access. For more information, see Limiting Server Directory Access on page 33. 4. Define database resources if applicable. To determine if you need to define database resources, expand the Modules node then expand each module. If there is a Tools node with a database resource icon under it, then you need to define database resources for that module. 5. Define the databases, file servers, and other data sources that you want to access from Spectrum™ Technology Platform. Administration Guide 11 Managing Security In this section: • • • • • • • • Security Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16 Secured Entity Overrides . . . . . . . . . . . . . . . . . . . . . . . . . .21 Security for the Location Intelligence Module . . . . . . . . .23 Disabling User Security . . . . . . . . . . . . . . . . . . . . . . . . . . .33 Limiting Server Directory Access . . . . . . . . . . . . . . . . . . .33 Configuring HTTPS Communication . . . . . . . . . . . . . . . . .35 2 Security Model Security Model Spectrum™ Technology Platform uses a role-based security model to control access to the system. The following diagram illustrates the key concepts in the Spectrum™ Technology Platform security model: A user is an account assigned to an individual person which the person uses to authenticate to Spectrum™ Technology Platform, either to one of the client tools such as Enterprise Designer or Management Console, or when calling a service through the API. A user has one or more roles assigned to it. A role is a collection of permissions that grant or deny access to different parts of the system. Roles typically reflect the kinds of interactions that a particular type of user has with the system. For example, you may have one role for dataflow designers which grants access to create and modify dataflows, and another role for people who only need to process data through existing dataflows. A role grants permissions to secured entity types. A secured entity type is a category of items to which you want to grant or deny access. For example, there is a secured entity type called "Dataflows" which controls the default permissions for all dataflows on the system. If you need to fine-tune access you can optionally specify secured entity overrides. A secured entity override controls access to a specific secured entity on the system. For example, the secured entity type "Dataflows" specifies the default permissions for all dataflows on the system, while each individual dataflow is a secured entity. If you want to grant or deny access to a specific dataflow, you would specify a secured entity override for the dataflow. You can specify secured entity overrides for a user, which overrides the permissions granted to the user by the user's roles. You can also specify secured entity overrides for roles, which applies the overrides to all users who have that role. You can only apply overrides for roles and users that you create, not for predefined roles and users. Related Links Disabling User Security on page 33 Creating a User on page 15 Creating a Role on page 17 Creating a Secured Entity Override on page 22 14 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security Users Spectrum™ Technology Platform user accounts control the types of actions users can perform on the system. User accounts are required to: • • • • Use Management Console, Enterprise Designer, or Interactive Driver Run jobs on a schedule Run jobs from the command line Access services through web services or the API There is an administrative account called admin that comes with the system. This account has full access. The initial password is "admin". Important: You should change the admin password immediately after installing Spectrum™ Technology Platform to prevent unauthorized administrative access to your system. In addition to these default accounts you can create as many user accounts as your business requires. Related Links Creating a Secured Entity Override on page 22 Creating a User This procedure describes how to create a Spectrum™ Technology Platform user account and assign a role to the account. 1. Open the Management Console. 2. Expand Security then click Users. 3. Click Add. The New User window appears. 4. Leave the Enable user box checked if you want this user account to be available for use. 5. Enter the user name in the User name field. Note: User names can only contain ASCII characters. 6. Enter the user's password in the Password field. 7. Reenter the user's password in the Confirm password field. 8. Enter the user's email address in the Email address field. 9. Enter a description of the user in the Description field. 10. Select the roles you want to give to this user. 11. Click OK. Related Links Security Model on page 14 Modifying a User This procedure describes how to modify an existing Spectrum™ Technology Platform user account. Note: You can modify all user information except user name. If you need to change a user name, you must first delete the user then create a user with the new user name. 1. Open the Management Console. 2. Expand Security then click Users. 3. Click Modify. Administration Guide 15 Roles The User Properties window appears. 4. Leave the Enable user box checked if you want this user account to be available for use. 5. Enter the user's password in the Password field. 6. Reenter the user's password in the Confirm password field. 7. Enter the user's email address in the Email address field. 8. Enter the description of the user in the Description field. 9. Select the roles you want to give to this user. 10. Click OK. Disabling a User Account You can disable a user account so that it cannot be used to gain access to Spectrum™ Technology Platform. When a user account is disabled it cannot be used to access Management Console, Enterprise Designer, or Interactive driver. In addition, any jobs that run on a schedule using a disabled user account will not run. API calls that use a disabled user account will also not work. Note: The user account "admin" cannot be disabled. 1. Open Management Console. 2. Expand Security then click Users. 3. Select the user account you want to disable and click Modify. 4. Clear the Enable user check box. The user account is now disabled and cannot be used to gain access to Spectrum™ Technology Platform. Deleting a User This procedure describes how to permanently delete a Spectrum™ Technology Platform user account. Tip: User accounts can also be disabled, which prevents the account from being used to access the system without deleting the account. 1. Open the Management Console. 2. Expand Security then click Users. 3. From the User Management screen, select the user you want to delete and click Delete. 4. Click Yes to delete or No to cancel. Note: The user account "admin" cannot be deleted. Roles A role is a collection of permissions that grant or deny access to different parts of the system. Roles typically reflect the kinds of interactions that a particular type of user has with the system. For example, you may have one role for dataflow designers which grants access to create and modify dataflows, and another role for people who only need to process data through existing dataflows. The following roles are predefined: 16 admin This role has full access to all parts of the system. designer This role is for users that create dataflows and process flows in Enterprise Designer. It provides the ability to design and run dataflows. Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security integrator This role is for users who need to process data through Spectrum™ Technology Platform but does not need to create or modify dataflows. It allows the user to access services through web services and the API, and to run batch jobs. spatial-admin This role is available only when the Location Intelligence Module module is installed. It provides full access to named resources for this module when using spatial services. (Additional access is required to manage spatial resources using Management Console. See Security for the Location Intelligence Module on page 23 for more information.) spatial-user This role is available only when the Location Intelligence Module module is installed. It provides read-only access to named resources for this module when using spatial services. (Additional access is required to view spatial resources using Management Console. See Security for the Location Intelligence Module on page 23 for more information.) user This is the default role. It provides no access to the system. Users who have this role will only gain access to the system if you grant permission through secured entity overrides. To view the permissions granted to each of these roles, open Management Console, go to Security and click Roles. Then select the role you want to view and click View. Tip: You cannot modify the predefined roles. However, you can create new roles using the predefined roles as a starting point. Related Links Creating a Secured Entity Override on page 22 Creating a Role A role is a collection of permissions that you assign to a user. If the predefined roles that come with Spectrum™ Technology Platform do not fit your organization's needs, you can create your own roles. 1. In the Management Console, browse to Security then expand Roles. 2. Click Add. 3. In the Role field, enter the name you want to give to this role. The name can be anything you choose. 4. If you want to use one of the predefined roles as a starting point for your new role, check the Copy from box then select the role that you want to use as a starting point. The predefined role's permissions are selected for you. 5. Optional: Since the list of secured entity types can be long, you may want to display only a certain group of secured entity types. This can be useful if you want to apply the same permissions to all entities in a group. For example, if you want to remove the Modify permission from all database resources, you could filter to show just the Database Resources group. To display and modify only one group: a) b) c) d) Check the Enable group filtering box. Click the funnel icon in the header of the Group column and select the group you want to display. Check or clear the box in the column header of the permission you want to apply. To return to the full list of secured entity types, click the filter icon and select (All) then clear the Enable group filtering box. 6. Select the permissions you want to grant for each entity type. The permissions are: View Allows the user to view entities contained by the entity type. For example, if you allow the View permission for the JDBC Connection entity type, users with this role would be able to view database connections in Management Console. Modify Allows the user to modify entities contained by the entity type. For example, if you allow the Modify permission for the JDBC Connection entity type, users with this role would be able to modify database connections in Management Console. Create Allows the user to create entities that fall into this entity type's category. For example, if you allow the Create permission for the JDBC Connection entity type, users with this role would be able to create new database connections in Management Console. Administration Guide 17 Roles Delete Allows the user to delete entities contained by the entity type. For example, if you allow the Delete permission for the JDBC Connection entity type, users with this role would be able to delete database connections in Management Console. Execute Allows the user to initiate processing of jobs, services, and process flows. For example, if you allow the Execute permission for the Job entity type, users with this role would be able to run batch jobs. If you allow the Execute permission for the Service entity type, users with this role would be able to access services running on Spectrum™ Technology Platform through the API or web services. 7. Click OK. The role is now available to be assigned to a user. Note: You can delete a role that you create, but only after you unassign it from all user accounts. Related Links Security Model on page 14 Secured Entity Types - Platform An entity type is a category of items to which you want to grant or deny access. For example, there is an entity type called "Dataflows" which controls permissions for all dataflows on the system. Platform entity types apply to all Spectrum™ Technology Platform installations, as compared to module-specific entity types that apply only if you have installed particular modules. The platform-level entity types are: Dataflows Controls access to all dataflow types (jobs, services, and subflows) in Enterprise Designer. Dataflows - Expose Controls the ability in Enterprise Designer to make dataflows available for execution. Event Log Controls access to the Event Log node in Management Console. Execution - File Monitor and Scheduling Controls access to job schedule and file monitor configuration in Management Console. Execution - Job Options Controls access to the Job Options node in Management Console. All users have View access to job options. You cannot remove View access. Execution - Report Options Controls access to the Report Options node in Management Console. All users have View access to report options. You cannot remove View access. Execution - Sort Performance Controls access to the Sort Performance node in Management Console. All users have View access to sort performance options. You cannot remove View access. Execution - Type Conversion Options Controls access to the Type Conversion node in Management Console. All users have View access to type conversion options. You cannot remove View access. Execution History - Jobs Controls access to job execution history in Enterprise Designer and Management Console. Execution History - Process Flows Controls access to process flow execution history in Management Console and Enterprise Designer. Jobs Controls the ability to execute jobs in Enterprise Designer, Management Console, and job executor. Notification - License Expiration Controls access to configure license expiration notification emails in Management Console. 18 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security Notification - SMTP Settings Controls access to the email notification options in Management Console. Process Flows Controls access to process flows in Enterprise Designer. Process Flows - Expose Controls the ability in Enterprise Designer to make process flows available for execution. Remote Server Controls access to the Remote Servers node in Management Console. Resources - Database Connections Controls the ability to configure JDBC connections in Management Console. Resources - External Web Services Controls access to managing external web services in Management Console. Resources - File Servers Controls the ability to configure file servers in Management Console. Resources - JDBC Drivers Controls the ability to configure JDBC drivers in Management Console. Resources - Restrict server directory access Controls the ability to enable or disable restrictions on server directory resources in Management Console. Resources - Server directory paths Controls the ability to configure server directory resources in Management Console. Security - Options Controls access to the Security Options node in Management Console. Security - Roles Controls access to role configuration in Management Console. Security - Secured Entity Overrides Controls access to secured entity overrides in Management Console. Security - Users Controls access for managing user accounts in the Users node of Management Console. Services Controls the ability to execute services through the API and web services. Stages Controls whether exposed subflows are available as a stage in dataflows in Enterprise Designer. System - Licensing Controls access to the license information displayed in Management Console. System - Version Information Controls access to the Version Information node in Management Console. Transaction History Controls access to the Transaction History node in Management Console. Secured Entity Types - Advanced Matching Module An entity type is a category of items to which you want to grant or deny access. The following entity types control access to parts of the Advanced Matching Module. Match Rules Management Controls access to the match rules in the Interflow Match stage, Intraflow Match stage, Transactional Match stage, and Match Rules Management Tool in Enterprise Designer. Search Index Management Administration Guide Controls access to search indexes in Write to Search Index, Candidate Finder, and the Search Index Management Tool in Enterprise Designer. 19 Roles Secured Entity Types - Business Steward Module An entity type is a category of items to which you want to grant or deny access. The following entity type controls access to parts of the Business Steward Module. Exceptions Controls the ability to modify or delete exception records assigned to other users in the Read Exceptions stage and the Exception Editor. Also controls the ability to review and manage exception record activity in the Exception Manager and enables access to Performance data in the Business Steward Portal. Users with Modify permissions for the Business Steward Portal group must also have Security-Users View permissions for the Platform group in order to assign or reassign exception records. Secured Entity Types - Data Hub Module An entity type is a category of items to which you want to grant or deny access. The following entity types control access to parts of the Data Hub Module. Algorithms Controls the ability to execute algorithms in the Relationship Analysis Client. Model Admin Controls the ability for users to perform the following actions using Data Hub stages and the Relationship Analysis Client: • • • • Read model data: entities, relationships, and their properties Create models and model data: entities, relationships, and their properties Modify model data: entities, relationships, and their properties Delete models and model data: entities, relationships, and their properties For example, if you had a model comprised of insurance data, you might have doctors and patients as entities, with relationships such as "visited" or "filed a claim for," and properties that depict the dates for those visits or claims. Using this example, the Model Admin entity type would allow you to grant permissions for the following actions: • Read data for doctors and patients and their visit or claim properties • Create doctor and patient entities, link them together with visit or claim relationships, and include any properties such as addresses, claim IDs, dates, and so on. • Modify doctor and patient entities, their relationships, and their properties such as addresses, claim IDs, dates, and so on. • Delete doctors and patients from the model Model Metadata Controls the ability for users to perform the following actions using Data Hub stages and the Relationship Analysis Client: • • • • Read entity types and relationship types Create entity types, relationship types, and their properties Modify entity type properties and relationship type properties Delete entities and relationships Note: This permission includes clearing a model in the Write to Hub stage. Monitor Admin Controls the ability to create monitors in the Relationship Analysis Client that detect changes to a model's entities or relationships. Theme Admin Controls the ability to define themes for models in the Relationship Analysis Client. 20 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security Secured Entity Types - Data Normalization Module An entity type is a category of items to which you want to grant or deny access. The following entity types control access to parts of the Data Normalization Module. Advanced Transformer Tables Controls access to the Advanced Transformer tables in the Table Management tool in Enterprise Designer. Open Parser Cultures Controls access to cultures in the Open Parser Domain Editor tool in Enterprise Designer. Open Parser Domains Controls access to domains in the Open Parser Domain Editor tool in Enterprise Designer. Open Parser Tables Controls access to the Open Parser tables in the Table Management tool in Enterprise Designer. Standardization Tables Controls access to the Standardization tables in the Table Management tool in Enterprise Designer. Secured Entity Types - Enterprise Data Integration Module An entity type is a category of items to which you want to grant or deny access. The following entity types control access to parts of the Enterprise Data Integration Module. Cache Controls access to caches used by the Write to Cache and Query Cache stages, and the Cache Management tool in Management Console. Secured Entity Types - Location Intelligence Module An entity type is a category of items to which you want to grant or deny access. The Location Intelligence Module has the following module-specific entity type: Named Resources Controls permissions to all named resources in the Location Intelligence Module, including named maps, named tiles, named tables, and named connections. Users of Location Intelligence Module services must have at least read permissions for the resources they use as well as for any dependent resources. Secured Entity Types - Database Resources An entity type is a category of items to which you want to grant or deny access. Database resources are available depending on which modules you have installed, for example: • Centrus Database Resources • Enterprise Routing • Spatial Database Resources Secured Entity Overrides A secured entity override controls access to a specific secured entity on the system. For example, the secured entity type "Dataflows" specifies the default permissions for all dataflows on the system, while each individual dataflow is a secured entity. If you want to grant or deny access to a specific dataflow, you would specify a secured entity override for the dataflow. You can specify secured entity overrides for a user, which overrides the permissions granted to the user by the user's roles. You can also specify Administration Guide 21 Secured Entity Overrides secured entity overrides for roles, which applies the overrides to all users who have that role. You can only apply overrides for roles and users that you create, not for predefined roles and users. Creating a Secured Entity Override A secured entity override specifies permissions for specific secured entities in the system, such as specific dataflows or specific database connections. To create a secured entity override: 1. In Management Console, expand Security then click Secured Entity Overrides. 2. Do one of the following: • If you want to specify a secured entity override for a role, click Role. The overrides you specify will affect all users who have the role you choose. • If you want to specify a secured entity override for a user, click User. The overrides you specify will only affect the user you choose. 3. Click Browse to select the specific role or user then click OK. 4. Click Add then Browse. The Select Secured Entity Type window appears. 5. Select the secured entity type that contains the secured entity you want to override then click OK. For example, if you want to override a dataflow secured entity, choose Platform.Dataflows. Tip: To select multiple secured entity overrides, use CTRL+click. To select a range of secured entity overrides, use SHIFT+click. 6. Choose the secured entity that you want to override. Click Add then Close. The secured entities you chose are displayed. The secured entity type's row shows the permissions in effect for the selected role or user. A gray checked box indicates that the permission is enabled and a gray empty box indicates that the permission is disabled. 7. Specify the secured entity overrides you want. Each permission can have one of the following settings: There is no override for the permission. The permission is the default permission granted to the user or role. The permission is denied to the user or role, overriding whatever permission is specified in the secured entity type. The permission is granted to the user or role, overriding whatever permission is specified in the secured entity type. Secured Entity Override Example The following shows a secured entity override for the role RetentionDepartmentDesigner. In this example, the Platform.Dataflow secured entity type is set to allow the View and Modify permissions but not the Delete permission. So by default, any user that has the RetentionDepartmentDesigner role would have these permissions for all dataflows. However, you want to prevent users with this role from modifying the GeoConfidenceSurface dataflow only. So, you clear the checkbox in the Modify column 22 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security for the GeoConfidenceSurface secured entity. Now users with this role will not be able to modify this dataflow but will still be able to modify other dataflows. You also want to make sure that users with this role always have the ability to modify the GeocodeAddress dataflow even if the secured entity type's permissions are changed at the role level. So, you place a check mark in the Modify column for GeocodeAddress, replacing the block. Now, even if the Platform.Dataflow secured entity type is changed to remove the Modify permission, users with this role will still be able to modify the GeocodeAddress dataflow. Related Links Security Model on page 14 Security for the Location Intelligence Module on page 23 Users on page 15 Roles on page 16 Viewing a Secured Entity Override A secured entity override specifies permissions for specific secured entities in the system, such as specific dataflows or specific database connections. To view secured entity overrides for a role or user: 1. In Management Console, expand Security then click Secured Entity Overrides. 2. Do one of the following: • If you want to view a secured entity override for a role, click Role. • If you want to view a secured entity override for a user, click User. 3. Click Browse to select the specific role or user then click OK. The secured entities with overrides for the role or user you chose are displayed. The secured entity type's row (for example, Platform.Dataflows) shows the permissions in effect for the selected role or user. A gray checked box indicates that the permission is enabled and a gray empty box indicates that the permission is disabled. The secured entity rows (for example, the specific dataflow GeocodeAddress) shows the permissions in effect for that entity, each of which can have one of the following settings: There is no override for the permission. The permission is the default permission granted to the user or role. The permission is denied to the user or role, overriding whatever permission is specified in the secured entity type. The permission is granted to the user or role, overriding whatever permission is specified in the secured entity type. Security for the Location Intelligence Module The Location Intelligence Module uses the same role-based security that is used for the Spectrum™ Technology Platform. Because security is handled at the platform level, the Management Console can be used to manage all Location Intelligence Module security activities. This includes setting permissions for named resources in addition to managing user accounts (that is, creating, modifying, and deleting user accounts). Note: The User Management Service can still be used to set permissions if desired; however, permissions are stored in the platform and not the repository, and cannot be set at the folder or directory level. The User Management Service is set to be deprecated in the next release. Administration Guide 23 Security for the Location Intelligence Module After you install the Location Intelligence Module, two predefined roles are available in Management Console, spatial-admin and spatial-user. The spatial-admin role provides full permissions (View/Modify/Create/Delete) for all named resources (named maps, named tiles, named connections, and named tables), whereas the spatial-user role provides only View permissions to these resources. These permissions are controlled using the Location Intelligence Module's secured entity type, Location Intelligence.Named Resources. Users of Location Intelligence Module services must have at least View permissions for the resources they use as well as for any dependent resources. These predefined spatial roles, when assigned to a user, provide access to named resources only when using spatial services. They do not allow access to named resources in Management Console. The "admin" user in Spectrum has full access to manage all parts of the system, including named resources, via the Management Console. If you also want users who can access only named resources via the Management Console, you must manually create a "named resources administrator" role, using one of the predefined spatial roles as a base, that provides access to named resources in the repository then assign that role to a "named resources administrator" user account. For instructions on creating this additional resource-administrator role, see Creating a Named Resources Administrator on page 30. Dataflow designers who require access to named resources also need additional permissions beyond that of the "designer" role. For instructions on creating a spatial dataflow designer, see Creating a Spatial Dataflow Designer on page 31. Roles and associated permissions on the Location Intelligence.Named Resources secured entity type can all be viewed using Management Console. • Predefined roles, which are not editable: • Permissions for spatial-admin, on the Location Intelligence.Named Resources secured entity: • Permissions for spatial-user, on the Location Intelligence.Named Resources secured entity: 24 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security Note: The permission settings in the User Management Service are mapped to the Spectrum™ Technology Platform as follows: Read>View, Modify>Modify, Add>Create, and Remove>Delete. You can create custom roles based on the predefined spatial roles, assign them to user accounts, then fine-tune access to named resources for those roles and users by applying secured entity overrides to individual named resources. Overrides cannot be applied to folders or directories, so anytime a named resource is added you must specify any necessary overrides for that resource. Related Links Creating a Secured Entity Override on page 22 Example: Overriding Permissions at the Role Level A typical scenario and best practice for setting security for the Location Intelligence Module involves creating a custom role with no permissions, applying specific overrides to the custom role, then assigning that role to a user. In this example, you will: 1. Create a custom role with no permissions. 2. Apply overrides to the custom role allowing modify and delete permissions for named tables in the repository. 3. Create a user account and assign the custom role along with a pre-defined spatial role to it. Step 1. Creating a Custom Role If the predefined roles that come with Spectrum™ Technology Platform do not fit your organization's needs, you can create your own roles. In this example, you will create a custom role called table-modifier that initially has no permissions. Note: Before you begin, verify that security is enabled, see Disabling User Security on page 33. 1. In the Management Console, browse to Security then click Roles. 2. Click Add. The Add Role dialog appears. 3. In the Name field, enter the name you want to give to this role, table-modifier. No permissions are set for this role. Administration Guide 25 Security for the Location Intelligence Module 4. Click OK. The role is now available to be assigned overrides. Step 2. Applying Overrides to a Role A secured entity override grants permissions for specific secured entities in the system, such as named tables that are in the repository. In this step of the example, you will create an override for the table-modifier role that allows modifying and deleting of named tables: 1. In Management Console, expand Security then click Secured Entity Overrides. 2. Click Role then Browse. The Select Role dialog appears. 3. Select the table-modifier role and click OK. 4. Click Add. The Select Items dialog appears. 26 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security 5. Click Browse. The Select Secured Entity Type window appears. 6. Select the Location Intelligence.Named Resources secured entity type. Click OK. A list of all secured entities that are named resources appears. 7. From the list of secured entities, locate then select all the named table resources (use the Shift key to select multiple consecutive items in this dialog). Note: Overrides can be applied only to individual named resources, not to folders or directories. 8. Click Add then Close. The secured entities (named tables) you chose are displayed. The secured entity type's row shows the permissions in effect for the table-modifier role. A gray checked box indicates that the permission is enabled and a gray empty box indicates that the permission is disabled. 9. Specify overrides on each secured entity (named table) by selecting all checkboxes in the Modify and Delete columns: 10. Click Save or select File > Save. The asterisk next to the "Secured Entity Overrides" window title no longer appears, indicating that the changes are saved. The table-modifier role now permits modifying and deleting of named tables, and can be assigned to a user account. Note: If named tables are subsequently added to the repository, you will need to add security entity overrides for each of those named tables. Step 3. Creating a User In the final step of this example, you will create a user account to which you will assign both the pre-defined spatial-user role (which provides view-only permissions to named resources) as well as the custom table-modifier role (which grants additional permissions for modifying and deleting named tables). 1. In Management Console, expand Security then click Users. 2. Click Add. The New User window appears. Administration Guide 27 Security for the Location Intelligence Module 3. Leave the Enable user box checked if you want this user account to be available for use. 4. Enter the user name (user-tables) in the User name field. 5. Enter the user's password in the Password field. 6. Re-enter the user's password in the Confirm password field. 7. Enter the user's email address in the Email address field. 8. Enter a description of the user in the Description field. 9. Select the spatial-user and table-modifier roles. 10. Click OK. A user-tables user account is now available with view-only permissions to all named resources as well as modify and delete permissions for named tables. Example: Overriding Permissions at the User Level Another scenario for setting security for the Location Intelligence Module involves establishing override permissions for a single user. In this example, you will: 1. Create a user with view-only permissions to named resources. 2. Apply overrides to the user account that allow modifying and deleting of a specific named tile. Step 1. Creating a User with View Permissions First, you will create a user account to which you will assign the pre-defined spatial-user role. This role provides view-only permissions to named resources. 1. In Management Console, expand Security then click Users. 28 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security 2. Click Add. The New User window appears. 3. Leave the Enable user box checked if you want this user account to be available for use. 4. Enter the user name (user-tiles) in the User name field. 5. Enter the user's password in the Password field. 6. Re-enter the user's password in the Confirm password field. 7. Enter the user's email address in the Email address field. 8. Enter a description of the user in the Description field. 9. Select the spatial-user role. 10. Click OK. A user-tiles user account is now available with view-only permissions to all named resources. Step 2. Applying Overrides to a User A secured entity override grants permissions for specific secured entities in the system. In the final step of this example, you will create an override that allows a single user (user-tiles) to modify and delete a specific named tile in addition to being able to view all types of named resources: 1. In Management Console, expand Security then click Secured Entity Overrides. 2. Click User then Browse. The Select User dialog appears. 3. Select the user (user-tiles) and click OK. 4. Click Add. The Select Items dialog appears. Administration Guide 29 Security for the Location Intelligence Module 5. Click Browse. The Select Secured Entity Type window appears. 6. Select the Location Intelligence.Named Resources secured entity type. Click OK. A list of all secured entities that are named resources appears. 7. From the list of secured entities, locate then select /Samples/NamedTiles/USATile. 8. Click Add then Close. The secured entity (named tile) you chose is displayed. The secured entity type's row shows the permissions in effect for the user-tiles user. A gray checked box indicates that the permission is enabled and a gray empty box indicates that the permission is disabled. 9. Specify overrides on the secured entity (named tile) by selecting the checkboxes in the Modify and Delete columns: 10. Click Save or select File > Save. The asterisk next to the "Secured Entity Overrides" window title no longer appears, indicating that the changes are saved. The user-tiles user can now modify, delete, and view a specific named tile (/Samples/NamedTiles/USATile), but can only view all other named tiles and named resources. Creating a Named Resources Administrator To view or manage named resources in the repository using Management Console, a user must have an assigned role that allows full access to those resources in addition to the access that is provided by the predefined spatial roles. The predefined spatial roles cannot be modified and a predefined "Named Resources Administrator" role is not provided by the Spectrum™ Technology Platform; however, you can create such a role using a predefined spatial role as a base. 1. In the Management Console, browse to Security then click Roles. 2. Click Add. 3. In the Name field, enter the name you want to give to this role (for example, "resource-admin"). 4. Check the Copy from box then select either the spatial-admin or spatial-user role to use as a starting point. The spatial-admin role provides View, Modify, Create, and Delete permissions for the Location Intelligence Module.Named Resources secured entity type; the spatial-user role provides View permissions. 5. Set additional permissions as follows for these secured entity types: Database Resources: • Centrus Database Resources to View/Modify/Create/Delete/Execute (if required) • Enterprise Routing to View/Modify/Create/Delete/Execute (if required) • Spatial Database Resources to View/Modify/Create/Delete/Execute for a spatial-admin, or to View/Execute for a spatial-user Platform: • • • • 30 Resources - File Servers to View Resources - JDBC Drivers to View Services to View/Modify/Execute System - Version Information to View Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security 6. Click OK to save the new resource-admin role. 7. Under Security, click Users. 8. Either select an existing user and click Modify, or click Add to create a new user. 9. Assign the new "resource-admin" role to the user account to allow it to manage and/or view named resources in Management Console. The user now has the access required to view and/or manage named resources in Management Console. Creating a Spatial Dataflow Designer To create dataflows for Location Intelligence Module stages and services, a user must have both the designer and spatial-user roles assigned. The spatial-user role provides View access to named resources under the Location Intelligence.Named Resources secured entity type. The designer role provides the necessary access to Platform secured entity types such as Dataflows. 1. In the Management Console, browse to Security then click Users. 2. Either select an existing user and click Modify, or click Add to create a new user. Administration Guide 31 Security for the Location Intelligence Module 3. Assign both the designer and spatial-user roles to the user account. The user now has permission to view named resources and design dataflows using those resources for Location Intelligence Module stages and services. Turning off Security for Services and the Repository All services and access to resources used by the Spectrum™ Technology Platform Location Intelligence Module are configured, by default, with authentication turned on. This allows certain functionality to restrict access to resources and the ability to modify resources in the repository. For example, the Named Resource Service AddNamedResource operation, and the CSW service Harvest operation both require authentication, as both of these operations require write permissions to the repository. The service-level authentication can be turned off for all services and the repository. This is useful if you have your own high-level authentication built into the solution that is using the Location Intelligence Module services. To turn off service and repository security, use the JMX console. 1. Access the JMX Console using the following URL: http://localhost:8080/jmx-console/ (replacing localhost and port 8080 with your correct configuration). 2. Under the Domain: com.pb.spectrum.platform.config section, select the administration link for the WebServiceSecurityConfigurationManager. 3. For RestServiceSecurityType and SoapServiceSecurityType enter OPEN in the value field and click set for each. 4. Restart the server. Once finished, security is turned off for the services and repository. Related Links 32 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security Disabling Platform Security Versus Turning Off Spatial Security on page 33 Disabling Platform Security Versus Turning Off Spatial Security The Spectrum™ Technology Platform allows you to disable role-based security at the platform level and service-level security as two separate operations. Disabling role-based security at the platform level (by deselecting ‘Limit access according to user permissions’ on the Security > Options node in Management Console) means that the permissions assigned to users (via roles and secured entity overrides) will not be enforced and all users will be able to access all parts of the system. The Location Intelligence Module will then allow access to any named resource in the repository. Turning off service-level security on the JMX Console (by setting RestServiceSecurityType and SoapServiceSecurityType to OPEN) causes the execution of service requests to use the admin user. For the Location Intelligence Module this means that any named resource that is added to the repository is “owned” by the admin user; therefore, running the User Management Service’s getPermissions request will show that non-admin users have only "Read" permissions. Disabling both service-level and role-based security completely opens up the Location Intelligence Module's services and named resources. Running the User Management Service’s getPermissions request will also show that non-admin users now have "All" permissions Related Links Disabling User Security on page 33 Turning off Security for Services and the Repository on page 32 Disabling User Security User security is enabled by default. This means that the security restrictions assigned to users through roles are enforced. If you want to disable user security, the security restrictions assigned to users will not be enforced and all users will be able to access all parts of the system. Note that a valid user account is always required to access services even if you disable user security. This procedure describes how to disable user security. Warning: If you follow this procedure all users will have full access to your Spectrum™ Technology Platform system. 1. Open the Management Console. 2. Expand Security then click Options. 3. Clear the Limit access according to user permissions check box. Related Links Security Model on page 14 Disabling Platform Security Versus Turning Off Spatial Security on page 33 Limiting Server Directory Access Enterprise Designer and Management Console users have the ability to browse the Spectrum™ Technology Platform server's folders and files, such as when selecting an input or output file when configuring a source or sink stage in a dataflow, or defining a database resource. You may want to restrict file browsing so that sensitive portions of the server are kept off limits. You can prevent all browsing or you can specify the folders that you want users to be able to browse. The folders you specify appear as Administration Guide 33 Limiting Server Directory Access the top-level folders in users' file browse windows. For example, if you allow users to only access a folder on the server named WestRegionCustomers, when users browse the server they would only see that folder, as shown here: To restrict access to the server's file system, follow this procedure. 1. Open Management Console. 2. Under Resources, select Server Directory Access. 3. Do one of the following: • To prevent users from browsing the server entirely, check the box Restrict server directory access and do not perform any of the following steps. Users will have no access to any of the files or folders on the server. • To allow access to some folders on the server, proceed to the following step. 4. Click Add. 5. In the Name field, give a meaningful name for the folder to which you are granting access. 6. In the Path field, specify the folder to which you want to grant access. Note: Users will be able to access all subfolders contained in the folder you specify. 7. Click OK. 8. If you want to grant access to additional folders, repeat the previous steps as needed. 9. Enforce the restrictions by checking the Restrict server directory access box. Users will now only have access to the folders you have specified. Note: If there are any dataflows that had previously accessed files that are no longer available because of file browsing restrictions, those dataflows will fail. 34 Spectrum™ Technology Platform 9.0 Chapter 2: Managing Security Configuring HTTPS Communication By default, Spectrum™ Technology Platform communication with the client tools (Enterprise Designer, Management Console, and Interactive Driver) and API occurs over HTTP. You can configure Spectrum™ Technology Platform to use HTTPS if you want to secure these network communications. 1. Stop the Spectrum™ Technology Platform server. • To stop the server on Windows, right-click the Spectrum™ Technology Platform icon in the Windows system tray and select Stop Server. Alternatively, you can use the Windows Services control panel and stop the Pitney Bowes Spectrum™ Technology Platform service. • To stop the server on Unix or Linux, source the /server/bin/setup script then execute the /server/bin/server.stop script. 2. Create a certificate and load it into a JSSE keystore. For more information, see http://docs.codehaus.org/display/JETTY/How+to+configure+SSL. 3. Create an XML file named spectrum-override-container-ssl.xml containing the following: 4. Modify the following lines as needed to reflect your environment: Modify the value to be the relative path from /server/app/conf/spring to the keystore you are using. This example assumes the keystore in the root of the drive on which the Spectrum™ Technology Platform server is installed. Modify the value to be the password to the key within the keystore. 5. Save the spectrum-override-ssl.xml file to /server/app/conf/spring. 6. Using a text editor, open the file spectrum-container.properties located in /server/app/conf and set the following properties: Administration Guide 35 Configuring HTTPS Communication spectrum.http.port=8443 spectrum.runtime.hostname=dnsname Where dnsname is the external DNS for the server. 7. Start the Spectrum™ Technology Platform server. • To start the server on Windows, right-click the Spectrum™ Technology Platform icon in the Windows system tray and select Start Server. Alternatively, you can use the Windows Services control panel to start the Pitney Bowes Spectrum™ Technology Platform service. • To start the server on Unix or Linux, execute the /server/bin/server.start script. 36 Spectrum™ Technology Platform 9.0 Configuring Database Resources In this section: • • • • Introduction to Database Resources . . . . . . . . . . . . . . . .38 Adding a Database Resource . . . . . . . . . . . . . . . . . . . . . .38 Optimizing Database Resources . . . . . . . . . . . . . . . . . . . .48 Deleting a Database Resource . . . . . . . . . . . . . . . . . . . . .49 3 Introduction to Database Resources Introduction to Database Resources Some modules rely on reference data to perform their processing. For example, the Universal Addressing Module uses databases containing postal data from postal authorities such as the United States Postal Service® to validate addresses. The Database Resources tool allows you to manage these databases. Adding a Database Resource Adding an Enterprise Geocoding Module Global Database Resource Unlike other stages, the Geocode Address Global and Reverse Geocode Global stages are not visible in Management Console, Enterprise Designer, or Interactive Driver until you define a database resource. New stages are created for each global database resource that you define. For example, if you define one database resource containing databases for Mexico and Canada, and another database resource containing data for Australia and Singapore, you would see two Geocode Address Global stages, one capable of geocoding addresses in Mexico and Canada and the other capable of geocoding addresses in Australia and Singapore. You would also see two Reverse Geocode Global stages, one for Mexico and Canada and one for Australia and Singapore. Note: • Australia, Canada, France, Germany, and Japan have large geocoding databases. Do not put more than one or two of these in the same database resource. • If you are running the Spectrum™ Technology Platform server on a 64-bit machine, database resources should contain no more than eight to ten countries. If you require more, Java memory settings need to be modified. For assistance, contact technical support. To create a Geocode Address Global database resource: 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Enterprise Geocoding > Tools then click Global Database Resources. 3. Click Add to create a new database resource or click Modify to change an existing database resource. 4. In the Name field, specify the name you want to give to this resource. This name can be anything you choose. You typically create a new database resource each time you receive an updated geocoding database from Pitney Bowes Software so you may want to consider using the database date in the database resource name. 5. Click Add. 6. Click Add again. 7. In the Name field, specify a name for this database path. This name can be anything you choose. 8. In the Path field specify the folder that contains the database files for the country you selected. The database files are typically found in: \IGEO-\\data where is the directory you specified when you installed the database files, is the two-letter country code, and is the version number of the data. Some countries may have multiple databases in the data directory, some of which you may have licensed and some you may have not. Only specify the location of the data you have licensed. Note: Do not put databases on a network drive. Doing so can cause performance problems. 9. If the database is a custom database, check the Custom database box. A custom database is a user-defined database that contains addresses and latitude/longitude coordinates that you can use for geocoding. 38 Spectrum™ Technology Platform 9.0 Chapter 3: Configuring Database Resources Note: If you are specifying a path for a custom database you must specify a path to a Pitney Bowes Software provided database first. The first path in all database resources must be a path for a Pitney Bowes Software provided database. 10. Click OK. 11. If you have additional database paths to add, click Add, otherwise click OK. 12. If you have additional countries to add, click Add, otherwise click OK. By adding multiple countries to the same database resource, you will create a Geocode Address Global stage that can geocode addresses for each country in one stage. 13. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 14. If there are any open Enterprise Designer sessions, click the refresh button to see the new stage. Adding an Enterprise Geocoding Module U.S. Database Resource Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to add or modify a U.S.database resource for the Enterprise Geocoding Module. For instructions on database resources for geocoding non-U.S. locations, see Adding an Enterprise Geocoding Module AUS or GBR Database Resource on page 40. 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Enterprise Geocoding > Tools > US Database Resources. 3. Click Add to install a new database or click Modify to change an existing database resource. 4. If you are adding a new database, enter a name for the database resource in the Name field. The name can be anything you choose. You cannot modify the name of an existing database resource. Changing the name of an existing database resource would cause any services or jobs that reference the database resource to fail. Note: If you are using the Enterprise Geocoding Module with the Siebel Module, name the U.S. geocoding database KGDDatasource. 5. In the Path elements field, specify the folder that contains the database files. You can include multiple database paths. This allows you to specify a single resource that includes both the primary database Link and any optional databases you may have, such as DPV, LACS , or elevation data. 6. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most Administration Guide 39 Adding a Database Resource modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 7. Click OK. Adding an Enterprise Geocoding Module AUS or GBR Database Resource Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to add or modify a database resource for the Enterprise Geocoding Module for Australia or Great Britain. 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Enterprise Geocoding > Tools then click the database resource icon for the country whose data you want to configure. 3. Click Add to install a new database or click Modify to change an existing database resource. 4. Specify a database resource name in the Database field. This name can be anything you choose. You typically create a new database resource each time you receive an updated geocoding database from Pitney Bowes Software so you may want to consider using the database date in the database resource name. 5. Click Add. In the Name field, specify a name for this database resource. In the Path field specify the folder that contains the database files. The database files are typically found in: \IGEO-\\data, where is the directory you specified when you installed the database files, is the two-letter country code, and is the version number of the data. Some countries may have multiple databases in the data directory, some of which you may have licensed and some you may have not. Only specify the location of the data you have licensed. For the Australia Geocoded National Address File (G-NAF) database, you must specify separate database resources for the GNAF123 and GNAF456 folders. We recommend that you use both databases to validate the existence of addresses but only use the GANF123 for parcel-level geocoding. If you do not require parcel-level geocodes you can use the GANF456 database for geocoding. Note: If you are specifying a path for a user-defined database you must specify a path to a Pitney Bowes Software provided database first. The first path in all database resources must be a path for a Pitney Bowes Software provided database. 6. Click OK. 7. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). 40 Spectrum™ Technology Platform 9.0 Chapter 3: Configuring Database Resources When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 8. Click OK. Adding an Enterprise Routing Module Database Resource Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to install or modify Enterprise Routing Module database resources. Routing database resources are used by Find Nearest, Get Travel Boundary, Get Travel Cost Matrix, and Get Travel Directions. 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Enterprise Routing > Tools > Routing Database Resources. 3. Click Add to install a new database or click Modify to change an existing database resource. 4. If you are adding a new database, enter a name for the database resource in the Name field. The name can be anything you choose. You cannot modify the name of an existing database resource. Changing the name of an existing database resource would cause any services or jobs that reference the database resource to fail. 5. In the Path elements field, specify the folder that contains the database files. The database files can be found in: \ERM-\\\ where is the directory you specified when you installed the database files, is the two-letter country code, is the date of the data (for example, 2009.1), is driving or pedestrian, and is the name of the country. 6. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 7. Click OK. Administration Guide 41 Adding a Database Resource Adding an Enterprise Tax Module Database Resource Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to add or modify Enterprise Tax Module database resources. 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Enterprise Tax > Tools > Database Resources. 3. Click Add to install a new database or click Modify to change an existing database resource. 4. If you are adding a new database, enter a name for the database resource in the Name field. The name can be anything you choose. You cannot modify the name of an existing database resource. Changing the name of an existing database resource would cause any services or jobs that reference the database resource to fail. 5. Specify the paths for the databases you want to include in this database resource. 6. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 7. Click OK. Adding a Location Intelligence Module Centrus Database Resource Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to install or modify a Location Intelligence Module database resource for a Centrus database. Centrus data is used by Closest Site and Point in Polygon. 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Location Intelligence > Tools > Centrus Database Resources. 3. Click Add to install a new database or click Modify to change an existing database resource. 4. If you are adding a new database, enter a name for the database resource in the Name field. The name can be anything you choose. You cannot modify the name of an existing database resource. Changing the name of an existing database resource would cause any services or jobs that reference the database resource to fail. 5. In the Path field, enter the full path to the database file(s). Centrus database files have a .gsb extension. The file names for .gsb files must be in all lower case on Unix and Linux systems for them to be available to Spectrum™ Technology Platform. 6. In the Cache Size field, select the amount of memory to use to use to cache data. In general, the larger the cache the better the performance. The options are: 42 Spectrum™ Technology Platform 9.0 Chapter 3: Configuring Database Resources • None—Do not cache data. • Medium—Use up to 5 MB of memory to cache data. Use this setting if there is a small amount of memory available for caching. • Large—Use up to 20 MB of memory to cache data. Use this setting if you are processing a large number of records. • Huge—Use up to 100 MB of memory to cache data. Use this setting if you are processing a large number of records. 7. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 8. Click OK.The list of databases includes this information: • Name—The name you have given the database. This is the name to use when referencing this database from a stage or service. • Path—The location of the database file. • Cache size—The amount of memory to use to cache data from this database. • Feature Type—Indicates the type of spatial data contained in the database (Points, Polygons, or Lines). Points databases can be used with the Closest Site and Point In Polygon stages. Polygon databases and Line databases can be used with Point In Polygon. • Buffered—Indicates whether or not the database supports buffering, which is a Point in Polygon feature that allows you to define areas that are close to the edge of a point, polygon, or line. Adding a Location Intelligence Module Database Named Connection Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to install or modify Location Intelligence Module spatial database resources. These resources are defined by adding a Named Connection to your database. These named connections are stored in the Location Intelligence Module repository, and can be used by all spatial services. Once you have added a Named Connection to a database, the database then becomes available to create Named Tables (links to tables in the database). Spatial database resources are used by Find Nearest, Query Spatial Data, and Read Spatial Data. Spectrum™ Technology Platform supports the following JDBC data types: BIGINT, BINARY, BIT, BLOB, BOOLEAN, CHAR, DATE, DECIMAL, DOUBLE, FLOAT, INTEGER, LONGVARBINARY, LONGVARCHAR, NULL, NUMERIC, REAL, SMALLINT, TIME, TIMESTAMP, TINYINT, VARBINARY, VARCHAR. In addition, Spectrum™ Technology Platform supports the following Oracle data types: SDO_GEOMETRY and MDSYS.SDO_GEOMETRY. These data types are handled as follows: • string , INTEGER, long, FLOAT, and DOUBLE—No changes. • DECIMAL—Converted to DOUBLE. Administration Guide 43 Adding a Database Resource • SDO_GEOMETRY and MDSYS.SDO_GEOMETRY—Converted to GEOMETRY. • All others—Converted to STRING. 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Location Intelligence > Tools > Named Connections. Then click one of the following: • Click Add to define a new database resource. • Click Modify to change an existing database resource. 3. If you are adding a new Named Connection, enter a name for the resource in the Connection Name field. The name can be anything you choose. You cannot modify the name of an existing database resource. Changing the name of an existing database resource would cause any services or jobs that reference the database resource to fail. 4. In the URL field, specify the JDBC connection URL to the database. This URL is in the format jdbc:[subprotocol]:[node]/[databaseName]. For example: • Oracle— jdbc:oracle:thin:@pbs-lim:8080:pbspatial • SQL Server—jdbc:sqlserver://PBS-LIM:8080;databaseName=pbspatial • PostGres/GIS— jdbc:postgresql://-:8080/pbspatial 5. In the User name field, specify the user for connecting to the database resource. 6. In the Password field, specify the password for the user connecting to the database resource. 7. In the Properties field, specify any database specific connection properties. Consult the database documentation for property names and value types that can be appended to a connection string. For example, property value networkProtocol and key tcp. Note: Oracle is currently the only database to support properties from the dialog. For the PostGres/GIS and SQL Server append properties to the URL. 8. Click Test to make sure your connection is valid. 9. Click OK. The Named Connection to the database resource now appears in the list of available resources in Find Nearest, Query Spatial Data, and Read Spatial Data. These connections can also be used to access Named Tables in database resources. Adding a Location Intelligence Module Named Table Resource Location Intelligence Module stages, services, and operations require Named Tables to access various types of data. Named Tables are a resource that point to data, and can be used to access MapInfo TAB (including View tables), Shape, JDBC database files (includes XY tables), or FDO database files (including text tables). This procedure describes how to add or modify Location Intelligence Module Named Table resources. These named tables are stored in the Location Intelligence Module repository, and can be used by all spatial services. Note: Only a user account with full permissions to named resources has the ability to add Named Tables using the Management Console. For more information on assigning permissions, refer to the "Managing Security" chapter in the Spectrum Spatial Administration Guide. 1. If you haven't already done so, install the data on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. For adding Named Tables that are in a database resource, you must first add the Named Connection to the database resource. For information on adding Named Connections, see Adding a Location Intelligence Module Database Named Connection on page 43. 2. In Management Console, expand Modules > Location Intelligence > Tools > Named Tables. Then click one of the following: • Click Add to define a new table resource. • Click Modify to change an existing table resource. 44 Spectrum™ Technology Platform 9.0 Chapter 3: Configuring Database Resources • Click Delete to remove an existing table resource. 3. If you are adding a new Named Table, enter the repository path and name for the named table resource in the Named table name field. You must prepend the name of the named table with where in the repository the named table is going to be created. For example, if you are creating the World named table and are creating this named table in the NamedTables folder in the repository, the name you would enter in the Named table name field would be /NamedTables/World. You cannot modify the name of an existing named table resource. Changing the name of an existing resource would cause any services or jobs that reference the resource to fail. 4. In the Named table type field select one of the following: • Tab—Choose this option if the data is in MapInfo TAB format on the file system. • Shape—Choose this option if the spatial data is in ESRI Shape file format. • Database—Choose this option if the data is in a JDBC database, and have created a Named Connection. • FDO—Choose this option if the data is in a FDO (SQLite) database, and have created a Named Connection. • View—Choose this option if the data is in MapInfo TAB format, and are using a SQL statement to display a particular view of the table. Note: When modifying a Named Table that has not been created using the Management Console (i.e., manually created and uploaded using the Named Resource Service or WebDav) the resource type might display as unknown. In this instance, the database connection information (JDBC or FDO) for the table has not been stored in the Management Console. To resolve the connection information, create a Named Connection in the Management Console to match the connection information in the Named Table you are trying to modify, then apply the new connection to the Named Table. 5. If you selected Tab as the source type, specify the path to the TAB file in the Path field. 6. If you selected Shape File as the source type, specify the path to the shape file in the Path field. 7. If you selected Database as the source type, complete these fields: • Connection name—The named connection to the database that defines a set of parameters used to access the database. Select a name from the list to specify an existing named connection. • Schema—The database schema object. This is typically the same as the user name. • Table—The table in the selected database containing the data you want to read into the dataflow. • XY—Check this box if your data is an XY table. Specify the X and Y columns and the coordinate system for these columns. In addition, select the styling of this table by either selecting None, defining a Style column, or defining a Named style. If selecting a named style, you must define an existing named style in the repository, and include the entire path from the root, e.g., /NamedStyles/PointStylePin. 8. If you selected FDO as the source type, complete these fields: • Connection name—The named connection to the database that defines a set of parameters used to access the database. Select a name from the list to specify an existing named connection. • Schema—The database schema object. For FDO this should be Default. • Table—The table in the selected database containing the data you want to read into the dataflow. 9. If you selected View as the source type, specify the SQL query in the SQL field. A View named table provides the ability to create a layer in a map based on the query in the named table at runtime. Using a View, you can create a named view containing a filtered view from multiple resources, based on a SQL query. Since your SQL query contains a named table (e.g., select Country,Capital, Obj from "/NamedTables/WorldcapTable" where Country='INDIA') you can use views on any datasource, as the named table might have a datasource type as TAB, XY, Oracle, SQL Server, etc. Once your SQL query is complete, click ValidateQuery to confirm your SQL statement is valid. 10. Click OK. The named table resource now appears in the list of available resources in Find Nearest, Query Spatial Data, and Read Spatial Data. Administration Guide 45 Adding a Database Resource Adding a Universal Addressing Module Database Resource Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to add or modify database resources used by Get Candidate Addresses, Get City State Province, Get Postal Codes, Validate Address. Note: If you want to configure a database resource for Validate Address Global, see Adding a Universal Addressing Module Global Database Resource on page 46. 1. If you haven't already done so, install the database files on your system. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. 2. In Management Console, expand Modules > Universal Addressing > Tools Click the icon for the country whose database resource you want to configure. Note: If you want to define a Global Database Resource for use with Validate Address Global, see Adding a Universal Addressing Module Global Database Resource on page 46. 3. Click Add to install a new database or click Modify to change an existing database resource. 4. If you are adding a new database, enter a name for the database resource in the Name field. The name can be anything you choose. You cannot modify the name of an existing database resource. Changing the name of an existing database resource would cause any services or jobs that reference the database resource to fail. 5. Specify the paths to the database files. 6. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 7. Click OK. Adding a Universal Addressing Module Global Database Resource Whenever you install a new database resource or modify an existing database resource you must define it in the Management Console in order for it to become available on your system. This procedure describes how to install or modify database resources for use with Validate Address Global. 1. If you have not already done so, install the database files on your system and enter the unlock key for the data in \server\modules\addressglobal\conf\unlockcodes.txt. For instructions on installing databases, see the Spectrum™ Technology Platform Installation Guide. Note: You must specify an unlock key in the file unlockcodes.txt before creating the database resource. 46 Spectrum™ Technology Platform 9.0 Chapter 3: Configuring Database Resources 2. In Management Console, expand Modules > Universal Addressing > Tools > Global Database Resources. 3. Click Add to install a new database or click Modify to change an existing database resource. 4. If you are adding a new database, enter a name for the database resource in the Name field. The name can be anything you choose. You cannot modify the name of an existing database resource. Changing the name of an existing database resource would cause any services or jobs that reference the database resource to fail. 5. In the Cache size field, choose the amount of memory you want to use for speeding up file system lookups in reference data that has not been preloaded. (Preloading is discussed below.) One of the following: • None—Do not cache data. • Small—Choose this option if you need to reduce the amount of memory used by Validate Address Global. • Large—This is the recommended setting. Use this setting unless all reference data is preloaded (in which case you may choose a cache size of None) or you want to reduce the amount of memory used by Validate Address Global. 6. In the Path elements field, specify the folder that contains the database files. To specify path elements, a) Click Add (or Modify to change an existing path). b) In the Path field specify the folder that contains the database files. c) Click Add to specify country preferences (or Modify to change an existing preference). 7. Select a database type. The options are: • Batch Interactive— (Default) Used for all non-FastCompletion and non-Certified databases. • FastCompletion—Validation mode used in quick address entry applications that allows input of truncated data in several address fields and will generate suggestions for this input. FastCompletion can also be used to create suggestions while you type. Note: FastCompletion databases do not support extended parsing. • Certified—Validation mode used in batch processing environments for Australian mail. Validate Address Global is certified by Australia Post's Address Matching Approval System (AMAS). It will standardize and validate your mail against the Postal Address File, providing postal discounts and allowing for the least amount of undeliverable pieces. 8. Select a preloading type. Preloading loads database data into memory, which can improve performance. Since large amounts of memory may be allocated during preloading, it might take some time to load the databases into memory. The options are: • None—No data is preloaded into memory. Use this option on machines with limited memory. (Default) • Partial—Partial preloading loads the metadata and indexing structures into memory. The reference data itself remains on the hard drive. Partial preloading offers some performance enhancements and is an alternative when not enough memory is available to fully load the desired databases. Partial preloading may not be supported for all databases. • Full—Full preloading moves the entire reference database into memory. This may need a significant amount of memory for countries with large databases such as the USA or the United Kingdom, but it will increase the processing speed significantly. 9. Choose one of the following: • Make default—Make the selected database type and preloading type the default for all countries in the folder. • Apply to selected countries only—Apply this database type and preloading type only to the selected countries. 10. Click OK. 11. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. Administration Guide 47 Optimizing Database Resources The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. 12. Repeat as needed to specify different database type and preloading settings for different countries. For example, if you have several countries in a folder you could specify a default database type of FastCompletion and preloading type of Partial then click OK. Then click Add, specify a default database type of FastCompletion and preloading type of Full for those few countries that you expect to use often, and click OK again. 13. When you are done defining database type and preloading options, click OK. 14. If necessary, define additional database paths. Click OK if you are done. The database resource now appears in the list of available database resources for Validate Address Global. Optimizing Database Resources Database resources contain reference data used by certain stages, such as postal data used to validate addresses, or geocoding data used to geocode addresses. These database resources can be configured to accept multiple concurrent requests from the dataflow stages or services that use them, thereby improving the performance of the dataflows or service requests. You can modify the number of concurrent requests that a database resource will accept by modifying the pool size of a database resource. The pool size determines the maximum number of concurrent requests that the database resource can process. By default, database resources have a pool size of 4, meaning the database resource can process four requests simultaneously. However, you can configure a database resource to have a different pool size. 1. Open Management Console. 2. Under Modules, expand the module for which you want to optimize database resource performance. Then expand Tools and select the database resource. 3. Select the database resource you want to optimize and click Modify. 4. In the Pool size field, specify the maximum number of concurrent requests you want this database to handle. The optimal pool size varies by module. You will generally see the best results by setting the pool size between one-half to twice the number of CPUs on the server, with the optimal pool size for most modules being the same as the number of CPUs. For example, if your server has four CPUs you may want to experiment with a pool size between 2 (one-half the number of CPUs) and 8 (twice the number of CPUs) with the optimal size possibly being 4 (the number of CPUs). When modifying the pool size you must also consider the number of runtime instances specified in the dataflow for the stages accessing the database resource. Consider for example a dataflow that has a Geocode US Address stage that is configured to use one runtime instance. If you set the pool size for the US geocoding database to four, you will not see a performance improvement because there would be only one runtime instance and therefore there would only be one request at a time 48 Spectrum™ Technology Platform 9.0 Chapter 3: Configuring Database Resources to the database resource. However, if you were to increase the number of runtime instances of Geocode US Address to four, you might then see an improvement in performance since there would be four instances of Geocode US Address accessing the database resource simultaneously, therefore using the full pool. Tip: You should conduct performance tests with various settings to identify the optimal pool size and runtime instance settings for your environment. Related Links Optimizing Services on page 68 Deleting a Database Resource 1. Before deleting a database, verify that there are no jobs or services using the database. Deleting a database that is referenced by jobs/services will cause those jobs/services to fail. 2. Click the Database Resources icon under the Tools node of the module for which you want to define a database. 3. Click Delete. Note: This process makes the database unavailable to Spectrum™ Technology Platform jobs but it does not delete the database files from your system. Administration Guide 49 Configuring Resources In this section: • • • • • Introduction to Resources . . . . . . . . . . . . . . . . . . . . . . . . .52 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 File Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 External Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 Using a Windows Mapped Drive . . . . . . . . . . . . . . . . . . . .62 4 Introduction to Resources Introduction to Resources In Spectrum™ Technology Platform, a resource is a connection to a data source that you want to use as input to, or output from, a dataflow. There are three kinds of resources: • Databases • File servers • Web services If you want to access data in an external resource you must first define a connection to the resource using Management Console. For example, if you want to read data from an XML file into a dataflow, and the XML file is located on a remote file server, you would have to define a connection to the file server before you can define the input XML file in a dataflow. Similarly, if you want to write dataflow output to a database, you must first define the database as an external resource. Note: If you want to read from or write to data located in a file on the Spectrum™ Technology Platform server itself there is no need to define a connection. Databases Adding or Modifying a Database Connection A database connection enables Spectrum™ Technology Platform to read and write data to a database. You must define a database connection in order to create dataflows that read data from the database or write data to the database. 1. Open the Management Console. 2. Expand Resources then click Connections. 3. Click Add or Modify. The Connection Properties dialog box will appear. 4. Enter a name for the connection in the Connection name field. This can be anything you choose. 5. Select the appropriate database type in the Database driver field. Spectrum™ Technology Platform comes with SQL Server and Oracle connection types. If you want to connect to a different database type, you must define a JDBC driver before configuring the database connection. 6. Complete the fields in the Connection Options table. This includes the host, port, instance, user name, and password. 7. Test the connection by clicking Test. 8. Click OK. Deleting a Database Connection 1. Open the Management Console. 2. Expand Resources then click Connections. 3. Highlight the connection you want to update and click Delete. You will receive a confirmation message asking if you wish to delete the connection. 4. Click OK to confirm. 52 Spectrum™ Technology Platform 9.0 Chapter 4: Configuring Resources JDBC Drivers Adding or Modifying a JDBC Driver Spectrum™ Technology Platform can read data from, and write data to, any database using a JDBC driver. To access data using a JDBC driver you must first define the driver, then create a database connection that uses the driver. The following procedure describes how to create or modify a JDBC driver. Note: JDBC driver settings are very specific and require total accuracy to function. Ensure you have the correct information from your database/database driver provider before adding a JDBC driver. 1. Open the Management Console. 2. Expand Resources then click JDBC Drivers. 3. Click Add to create a new JDBC driver connection. If you want to modify an existing drvier, select the driver you want to modify then click Modify. Note: Spectrum™ Technology Platform comes with three predefined JDBC drivers: Internal (which is used by the system), SQL Server, and Oracle. You cannot modify or delete these. 4. In the JDBC driver configuration name field, enter a name for the driver. The name can be anything you choose. 5. In the JDBC driver class name field, enter the Java class name of the driver. You can typically find the class name in your JDBC driver's documentation. For example, to use the Microsoft JDBC driver with an SSL connection to a SQL database, you might enter the following: com.microsoft.sqlserver.jdbc.SQLServerDriver 6. In the Connection string template field, enter the template to use for the connection string. For example, to enable an SSL connection to a SQL database, you would enter the following: jdbc:sqlserver://${host}:${port};databaseName=${instance};encrypt=true;TrustServerCertificate=true 7. In the Driver files section, click Add. 8. Navigate to and select the appropriate driver and click Save. 9. In the Connection Properties section, click Add. The JDBC Connection Property dialog box will appear. 10. In the Label field, enter the property's label. The label can be any name you choose. For example, username. 11. In the Property token field, enter the token to use in the URL. For example, user. Note: You will need to enter both user and password property tokens for every JDBC connection you create. 12. Click OK. Deleting a JDBC Driver 1. Open the Management Console. 2. Expand Resources then click JDBC Drivers. 3. Select an existing JDBC driver and click Delete. The Confirm Delete dialog box will appear. Note: If any connections are using this driver, you will be notified which connections are using it and you cannot delete the driver. Administration Guide 53 Databases Supported Database Data Types Spectrum™ Technology Platform supports the following data types commonly used in databases: bigdecimal A numeric data type that supports 38 decimal points of precision. Use this data type for data that will be used in mathematical calculations requiring a high degree of precision, especially those involving financial or geospatial data. The bigdecimal data type supports more precise calculations than the double data type. boolean A logical type with two values: true and false. date A data type that contains a month, day, and year. For example,- or January 30, 2012. You can specify a default date format in Management Console. datetime A data type that contain a month, day, year, and hours, minutes, and seconds. For example, 2012/01/30 6:15 PM. double A numeric data type that contains both negative and positive double precision numbers -1074 -52 1023 between 2 and (2-2 )×2 . In E notation, the range of values is 4.9E-324 to-E308. For information on E notation, see en.wikipedia.org/wiki/Scientific_notation#E_notation. float A numeric data type that contains both negative and positive single precision numbers - between 2 and (2-2 )×2 . In E notation, the range of values is 1.4E-45 to-E38. For information on E notation, see en.wikipedia.org/wiki/Scientific_notation#E_notation. integer A numeric data type that contains both negative and positive whole numbers between 31 31 -2 (-2,147,483,648) and 2 -1 (2,147,483,647). long A numeric data type that contains both negative and positive whole numbers between 63 63 -2 (-9,223,372,036,854,775,808) and 2 -1 (9,223,372,036,854,775,807). string A sequence of characters. time A data type that contains the time of day. For example, 21:15:59 or 9:15:59 PM. Other database data types are automatically mapped to one of the supported data types as follows: Table 1: Mapping of Database Data Types to Supported Data Types Database Data Type Supported Data Type Date/Time Types TIMESTAMP datetime String Types CHAR string CLOB string LONGVARCHAR string NCHAR string NVARCHAR string VARCHAR string Numeric Types 54 BIGINT long DECIMAL double Spectrum™ Technology Platform 9.0 Chapter 4: Configuring Resources Database Data Type Supported Data Type FLOAT double NUMERIC bigdecimal REAL float SMALLINT integer TINYINT integer Boolean Types BIT boolean File Servers Connecting to an FTP File Server If you need to read data from, or write data to, files on an FTP server you must define a connection to the file server using Management Console. Once you do this, you can create dataflows in Enterprise Designer that can read data from, and write data to, files on the file server. 1. Open the Management Console. 2. Expand Resources then click File Servers. 3. Click Add. 4. In the Connection name field, enter a name for the new connection . The name can be anything you choose. 5. In the Host field, enter the name or IP address of the FTP server. 6. In the Port field, enter the network port number. 7. In the Type field, choose FTP. 8. In the User name field, enter the user name to use when authenticating to the FTP server. This is required only if the FTP server requires it. 9. In the Password field, enter the password to use when authenticating to the FTP server. This is required only if the FTP server requires it. 10. Click OK. 11. If you wish to test the server, highlight the connection you want to test and click the Test button on the File Servers dialog box. After you have defined a connection to a file server, it becomes available in source and sink stages in Enterprise Designer, such as Read from File, Write to File, and so on. You can select the FTP server when you click Remote Machine when defining a file in a source or sink stage. Connecting to a Hadoop Distributed File System Hadoop Distributed File System (HDFS) is an open source distributed file system. It provides high-performance access to large data sets and can be run on inexpensive hardware. If you have an HDFS system you can configure Spectrum™ Technology Platform to read data from, or write data to, files on your HDFS cluster by defining a connection to the HDFS cluster using Management Console. Once you do this, you can create dataflows in Enterprise Designer that can access files on HDFS. Note: For more information on HDFS, see the documentation available on the Apache Hadoop project website: hadoop.apache.org. Administration Guide 55 File Servers 1. Open the Management Console. 2. Expand Resources then click File Servers. 3. Click Add. 4. In the Connection name field, enter a name for the new connection . The name can be anything you choose. 5. In the Host field, enter the name or IP address of the NameNode in the HDFS cluster. 6. In the Port field, enter the network port number. 7. In the Type field, choose HDFS. 8. Under User, select one of the following: Server user Choose this option if authentication is enabled in your HDFS cluster. This option will use the user credentials that the server runs under to authenticate to HDFS. User name Choose this option if authentication is disabled in your HDFS cluster. 9. In the Protocol field select one of the following: WEBHDFS Select this option if the HDFS cluster is running HDFS 1.0 or later. This protocol supports both read and write operations. HFTP Select this option if the HDFS cluster is running a version older than HDFS 1.0, or if your organization does not allow the WEBHDFS protocol. This protocol only supports the read operation. HAR Select this option to access Hadoop archive files. If you choose this option, specify the path to the archive file in the Path field. This protocol only supports the read operation. 10. If you selected the WEBHDFS protocol you can specify the following advanced options. Replication factor Specifies how many data nodes to replicate each block to. For example, the default setting of 3 replicates each block to three different nodes in the cluster. The maximum replication factor is 1024. Block size Specifies the size of each block. HDFS breaks up a file into blocks of the size you specify here. For example, if you specify the default 64 MB, each file is broken up into 64 MB blocks. Each block is then replicated to the number of nodes in the cluster specified in the Replication factor field. File permissions Specifies the level of access to files written to the HDFS cluster by Spectrum™ Technology Platform. You can specify read and write permissions for each of the following: Note: The Execute permission is not applicable to Spectrum™ Technology Platform. User This is the user specified above, either Server user or the user specified in the User name field. Group This refers to any group of which the user is a member. For example, if the user is john123, then Group permissions apply to any group of which john123 is a member. Other This refers to any other users as well as groups of which the specified user is not a member. 11. Click OK. 12. If you wish to test the server, highlight the connection you want to test and click the Test button on the File Servers dialog box. After you have defined a connection to an HDFS cluster, it becomes available in source and sink stages in Enterprise Designer, such as Read from File, Write to File, and so on. You can select the HDFS cluster when you click Remote Machine when defining a file in a source or sink stage. 56 Spectrum™ Technology Platform 9.0 Chapter 4: Configuring Resources Modifying a File Server 1. Open the Management Console. 2. Expand Resources then click File Servers. 3. Highlight the server you want to update and click Modify. 4. Make the appropriate changes to the server and click OK. Note: Modifying a configuration may cause any dataflows reference that configuration to no longer function properly. Deleting a File Server 1. Open the Management Console. 2. Expand Resources then click File Servers. 3. Highlight the file server you want to delete and click Delete. You will receive a confirmation message asking if you wish to delete the server. 4. Click OK to confirm. Note: Deleting a file server will cause any dataflows referencing that file server to no longer function properly. External Web Services External web services are data processing services provided over the Internet by a third party. You can define external web services in the Management Console and then use them as a stage in a dataflow, or as a service exposed on your Spectrum™ Technology Platform server. This allows you to incorporate almost any kind of processing into your Spectrum™ Technology Platform environment, since there are a wide variety of web services available on the Internet. External web services show up in the palette in Enterprise Designer and you can work with them as you do other stages. The following shows an example of two external web services, CompanyReviewsWebService and TimeZoneLookupWebService. Administration Guide 57 External Web Services Spectrum™ Technology Platform supports external web services that use REST, SOAP 1.1, or SOAP 1.2 messaging. Adding a SOAP Web Service This topic describes how to define a connection to an external third-party web service using the SOAP protocol. 1. Open the Management Console. 2. Expand the Resources node, then click External Web Services. 3. Click Add. 4. In the Name field, enter the name you want to give the external web service. This will be the stage name shown in Enterprise Designer and the service name on the Spectrum™ Technology Platform server. The name can be anything you want but must not already be used by another web service on your system. 5. Under External service type, select SOAP. 6. In the Timeout field, enter the number of seconds that are allowed to elapse before a request submitted to the web service times out. Note: The timeout value you specify here applies to any request made to the web service. This includes not only transactions made against the exposed web service, but also requests made in the course of configuring the web service. Such configuration requests are invoked by clicking Refresh, choosing a new item in the Operation list, and running preview. Timeouts can occur when performing any of these actions. If timeouts do occur, increasing the Timeout value can help to avoid them, provided the web service is actually up and running. 7. If you want to make the web service available to use in dataflows and to access as a Spectrum™ Technology Platform service: a) Check the Expose as service box. b) If you want the web service exposed as a SOAP web service, check the SOAP box. The web service will then be listed at http://:/soap. c) If you want the web service exposed as a REST web service, check the REST box. The web service will then be listed at http://:/rest. 8. In the URL field, enter the URL of the web service's WSDL. 9. Enter a user name and password if they are required to access the external web service. 58 Spectrum™ Technology Platform 9.0 Chapter 4: Configuring Resources 10. Click Refresh to populate the Operation list with the operations that are available from the web service. Note: Some web services require you to provide a user name and password before you can access them. In this case you must provide the required credentials prior to clicking Refresh. Otherwise, the refresh operation will fail. 11. In the Operation list, select the web service operation you want to perform. When you select a web service operation in the Operation list, the field names for the operation request and response are listed on the Request and Response tabs. 12. Check the Use WS-Security box to apply security to your web service by sending credentials through the header of the SOAP message. 13. If the web service supports request headers, configure the Request Header tab as follows. If it does not, go to step 14 on page 59. a) Select the header parameters you want to include in the request by checking or clearing the boxes. If a check box is checked and grayed out, it means that the parameter is required and you cannot disable it. b) In the Value column, specify the value you want to use for each parameter. 14. On the Request tab (or Request Body tab if the web service supports request headers), specify the settings and values you want for the request fields. a) To use a subset of the available request fields, select an XPath location in the Filter field. All XPath location paths that match the selected path, and any descendant paths, are displayed in the table and will be included in the request. b) In the Field Name column, enter the field name you want to reference each request field. This is the name that will be used for input field name for the resulting Spectrum™ Technology Platform service, if the field is exposed. Each XPath location in the table is associated with a corresponding request field. The request field is given an initial default name provided by the external web service. For each request field, you can either accept the default name or enter a new name. c) In the Default Value column, specify a default value for each request field, if desired. d) Select the Expose option for each request field you want to expose as an available input field in the resulting Spectrum™ Technology Platform service. If you want to expose all request fields, select the Expose option in the table heading row. e) If you want to view a template of the XML that will be sent as a request to the external web service, click View Template. 15. On the Response tab, specify the settings and values you want for the response fields. a) Select the Return response XML as text option if you want the external web service response to be returned as a single field named SoapResponse. A template of the XML response is displayed. Proceed to step 16 on page 60. If you do not select the Return response XML as text option, the web service response is returned as individual fields based on the specified mapping of field names to XPath location paths. Continue with the remaining steps below. b) If you want to filter the list of fields displayed, select an XPath in the Filter field. All XPath location paths that match the selected path, and any descendant paths, are displayed in the table and will be included in the response. c) In the Field Name column, change the default field name, if desired. Each XPath location path in the table is associated with a corresponding response field that is given an initial default name provided by the external web service. For each response field, you can either accept the default name or enter a new name. d) Select the Expose option for each response field you want to expose as an available output field in the resulting Spectrum™ Technology Platform service. If you want to expose all response fields, select the Expose option in the table heading row. A field which has its Expose option selected will be returned in the response from the external web service. Each field is mapped to an XPath location provided by the external web service. If the fields that have their Expose option selected are mapped to XPath locations that are all at Administration Guide 59 External Web Services the same level, then individual records will be returned for the fields. However, if the exposed fields are mapped to XPath locations at different levels, then a hierarchical data object will be returned. e) If you want to view a template of the XML that will be sent as a response from the external web service, click View Template. 16. On the Preview tab, enter any test data you would like to submit to the external web service, then click Preview to see the web service's response. 17. Click OK to save the external web service. Related Links External Web Services on page 57 Adding a REST Web Service This topic describes how to define a connection to an external third-party web service using the REST protocol. 1. Open the Management Console. 2. Expand the Resources node, then click External Web Services. 3. Click Add. 4. In the Name field, enter the name you want to give the external web service. This will be the stage name shown in Enterprise Designer and the service name on the Spectrum™ Technology Platform server. The name can be anything you want but must not already be used by another web service on your system. 5. Under External service type, select REST. 6. In the Timeout field, enter the number of seconds that are allowed to elapse before a request submitted to the web service times out. Note: The timeout value you specify here applies to any request made to the web service. This includes not only transactions made against the exposed web service, but also requests made in the course of configuring the web service. Such configuration requests are invoked by clicking Refresh, choosing a new item in the Operation list, and running preview. Timeouts can occur when performing any of these actions. If timeouts do occur, increasing the Timeout value can help to avoid them, provided the web service is actually up and running. 7. If you want to make the web service available to use in dataflows and to access as a Spectrum™ Technology Platform service a) Check the Expose as service box. b) If you want the web service exposed as a SOAP web service, check the SOAP box. The web service will then be listed at http://:/soap. c) If you want the web service exposed as a REST web service, check the REST box. The web service will then be listed at http://:/rest. 8. In the URL field, enter the URL of the web service. You may include parameters in the URL if you want to pre-populate the Request and Response tabs with the parameters used by the web service. For example, let's say you are defining an external web service for a web service that provides reviews of businesses. You might enter a URL like this: http://ws.someprovider.com/business_reviews?term=insurance&location=207325 Based on this, the external web service you define would have two fields, term and location. If you omit parameters from the URL you can specify them later in this procedure. 9. Enter a user name and password if they are required to access the external web service. 10. Click Refresh to populate the Operation list with the operations that are available from the web service. Note: Some web services require you to provide a user name and password before you can access them. In this case you must provide the required credentials prior to clicking Refresh. Otherwise, the refresh operation will fail. 60 Spectrum™ Technology Platform 9.0 Chapter 4: Configuring Resources 11. In the Operation list, select the web service operation you want to perform. When you select a web service operation in the Operation list, the field names for the operation request and response are listed on the Request and Response tabs. 12. On the Request tab, specify the settings and values you want for the request fields. a) The parameter list shows the parameters contained in the URL you previously entered. If you want to add additional parameters, click Add. If you want to delete a parameter, select it in the table and click Delete. b) In the Field Name column, enter the field name you want to reference each parameter. This is the name that will be used for input field name for the resulting Spectrum™ Technology Platform service, if the field is exposed. c) Specify a default value for each request field, if desired. d) Select the Expose option for each request field you want to expose as an available input field in the resulting Spectrum™ Technology Platform service. If you want to expose all request fields, select the Expose option in the table heading row. e) If you want to view a template of the request URL that will be sent to the external web service, click View Template. 13. On the Response tab, specify the type response returned by the third-party web service. Text Spectrum™ Technology Platform will return a single field named RestResponse containing the REST response. This option works with all response types. Delimited Select this option if the third-party web service returns delimited data such as CSV. Spectrum™ Technology Platform will parse the data and return it as individual fields. XML Select this option if the third-party web service returns XML. Spectrum™ Technology Platform will parse the data and return it as individual fields. JSON Select this option if the third-party web service returns JSON. Spectrum™ Technology Platform will parse the data and return it as individual fields. 14. On the Preview tab, enter any test data you would like to submit to the external web service, then click Preview. 15. Click OK to save the external web service. Related Links External Web Services on page 57 Renaming an External Web Service Renaming an external web service will break existing jobs/services that reference the external web service. If no jobs/services reference the external web service, or if you want to change existing jobs/services to reference a different external web service or the new name, you can safely rename the external web service. 1. In Management Console, expand the Resources node, then click External Web Services. 2. Highlight the external web service you want to rename and click Rename. 3. Confirm that you want to rename the external web service by clicking OK. 4. Enter a new name for the external web service, then click OK. Related Links External Web Services on page 57 Deleting an External Web Service Deleting an external web service will break existing jobs/services that reference the external web service. If no jobs/services reference the external web service, or if you want to change existing jobs/services to reference a different external web service, you can safely delete the external web service. 1. In Management Console, expand the Resources node, then click External Web Services. Administration Guide 61 Using a Windows Mapped Drive 2. Highlight the external web service you want to delete and click Delete. You will receive a confirmation message asking if you wish to delete the external web service. 3. Click OK to confirm. Related Links External Web Services on page 57 Using a Windows Mapped Drive If you are running the Spectrum™ Technology Platform server on a Windows server you can provide Enterprise Designer and Management Console users with access to data stored on a mapped drive. For example, you may want to design dataflows that read data from, or write data to, files located on a drive mapped to the Windows server running Spectrum™ Technology Platform. Since the Spectrum™ Technology Platform server runs as a Windows service under a particular user account (often the Local System account) you need to define the mapped drive in the server's start-up process in order for it to be visible in Enterprise Designer and Management Console. 1. Stop the Spectrum™ Technology Platform server. 2. Under the folder where the Spectrum™ Technology Platform server is installed, go to server\bin\wrapper. For example, C:\Program Files\Pitney Bowes\Spectrum\server\bin. 3. Open the file wrapper.conf in a text editor. Important: In the following steps you will add new properties to this file. It is important that you follow these instructions precisely and only add and modify the parameters described in the following steps. Do not modify any of the other parameters in this file. 4. Add the following lines: wrapper.share.1.location wrapper.share.1.target wrapper.share.1.type wrapper.share.1.account wrapper.share.1.password 5. In the wrapper.share.1.location property, specify the location of the mapped drive in UNC format. Note: Do not include a trailing backslash in the UNC. For example, wrapper.share.1.location=\\myserver\share 6. In the wrapper.share.1.target property, specify the drive letter to assign to this mapped drive. For example, wrapper.share.1.target=Y: 7. In the type property, specify DISK. For example, wrapper.share.1.type=DISK 8. If the share you are connecting to requires a user name and password, specify the user name in the wrapper.share.1.account property and specify the password in the wrapper.share.1.password property. 62 Spectrum™ Technology Platform 9.0 Chapter 4: Configuring Resources For example, wrapper.share.1.account=domain\user123 wrapper.share.1.password=mypassword1 Note: If the Spectrum™ Technology Platform server service is running under the Local System user, you cannot specify a user name and password. If the share requires a user name and password you must modify the service to run under a different account. Example of Mapped Drive Properties in Wrapper.conf The following example shows two mapped drives being defined in the wrapper.conf file. wrapper.share.1.location=\\myserver\data wrapper.share.1.target=Y: wrapper.share.1.type=DISK wrapper.share.1.account=sample\user wrapper.share.1.password=samplepass wrapper.share.2.location=\\myserver\moredata wrapper.share.2.target=Z: wrapper.share.2.type=DISK wrapper.share.2.account=sample\user wrapper.share.2.password=samplepass Administration Guide 63 Managing Execution In this section: • • • • • • • • Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66 Jobs and Process Flows . . . . . . . . . . . . . . . . . . . . . . . . . .68 Transaction History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 Remote Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 Optimizing Sort Performance . . . . . . . . . . . . . . . . . . . . . .78 Setting Default Type Conversion Options . . . . . . . . . . . .79 Configuring Remote Component Options . . . . . . . . . . . .84 JVM Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . .85 5 Services Services A service is a dataflow that you can access as web services or using the Spectrum™ Technology Platform API. You pass a record to the service and optionally specify the options to use when processing the record. The service processes the data and returns the data. Some services become available when you install a module. For example, when you install the Universal Addressing Module the service ValidateAddress becomes available on your system. In other cases, you must create a service in Enterprise Designer then expose that service on your system as a user-defined service. For example, the Location Intelligence Module's stages are not available as services unless you first create a service using the module's stages. Specifying Default Service Options Default service options control the default behavior of each service on your system. You can specify a default value for each option in a service. The default option setting takes effect when an API call or web service request does not explicitly define a value for a given option. Default service options are also the settings used by default when you create a dataflow in Enterprise Designer using this service. 1. Open Management Console. 2. Expand Modules, then expand the module that contains the service for which you want to specify default options. 3. Click the service you want. 4. Set the options for the service. 5. Select File > Save. Previewing a Service You can preview the results of a service using the Preview tab. Preview can be useful in helping you decide what options to specify because you can immediately see the effect that different options have on the data returned by the service. 1. Open Management Console. 2. On the left side of the Management Console, select a service. 3. Click the Preview tab. 4. Enter test input data manually or import data from a file. You do not have to enter data in every field. You can leave fields blank as necessary. • To enter data manually, simply type the test data into each field. • To import test data from a file, click the Import Data button. The maximum number of records you can import is limited to the maximum number of records your system is configured to process. For more information, see Limiting the Number of Records to Process on page 67. Note: If you import date or time data, the type conversion options for date and time data types will be used to parse the data for previewing. 5. Click Run Preview. Data will appear in the output grid. 66 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution 6. Review your output data, making sure the results are what you intended to get from the service. If necessary you can make changes to the service's settings and click Run Preview again. (You do not need to input the data again.) The default view is vertical. If you wish to change your view to horizontal, click View and select Horizontal. Limiting the Number of Records to Process 1. Open Management Console. 2. Click Tools > Options. 3. Click the Run Service Settings tab. 4. In the Maximum number of records to process field, enter the maximum number of records that a service can process. The maximum number you can enter is 100. Specifying a Field Separator A field separator, or delimiter, is the character used to mark the end of one field and the start of another when you use a flat file as input to a service. To specify the field separator to use for services, 1. Open Management Console. 2. Click Tools > Options. 3. Click the Run Service Settings tab. 4. In the File field separator field, specify the delimiter character to use. If the character you want is not listed, a) Click the . . . button. b) Click Add. c) After you enter or select a character press Tab. The Unicode field will automatically be completed. Alternatively, you may enter the unicode value and the Character field will automatically be completed. d) If you wish, enter a description of the character in the Description field. For example, if the character is "&" the description could be "ampersand." If you do not enter a description, the character will appear by itself in the list of available characters. Administration Guide 67 Jobs and Process Flows e) Click OK twice. Setting Service Timeout 1. Open Management Console. 2. Click Tools > Options. 3. Click the Run Service Settings tab. 4. In the Time-out in seconds field, specify the number of seconds to wait for a response before the service times out. Optimizing Services There are a number of different ways to call a Spectrum™ Technology Platform service and some of them perform better than others. The different ways of calling Spectrum™ Technology Platform services, in approximate order from fastest to slowest are: • Client API over SOCKET • • • • Client API over HTTP Client API over HTTPS XML over HTTP Web Services - SOAP and REST over HTTP Invoking a service through the client API is generally faster than calling the web service. The network protocol can have a significant effect on the round-trip time for the service call. For example, using the persistent SOCKET connection instead of HTTP can improve response time by 30%-50%. Performance in a real-time application calling Spectrum™ Technology Platform services also depends on whether the application is single-threaded or multi-threaded, and whether the server has the resources available to fulfill the service request. For a single-threaded client application, specifying additional instances of the remote component and/or additional runtime instances of a stage will have minimal impact on response time. A multi-threaded client application will generally benefit from multiple remote component instances and runtime instances, up to the number of concurrent threads. Related Links Optimizing Database Resources on page 48 Jobs and Process Flows A job is a dataflow that performs batch processing. A job reads data from one or more files or databases, processes that data, and writes the output to one or more files or databases. A process flow executes a series of activities such as Spectrum™ Technology Platform jobs and external applications. For example, a process flow could run a Spectrum™ Technology Platform job to standardize names, validate addresses, then invoke an external application to sort the records into the proper sequence to claim postal discounts. Use the Management Console to set global job and process flow settings and manage job and process flow execution. To create or edit jobs and process flows, use Enterprise Designer. Scheduling Jobs and Process Flows If you have jobs or process flows that you want to run automatically at a specified time, use the Management Console to set up job and process flow execution schedules. 1. If you have not already done so, expose the job or process flow. 68 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution You can expose jobs an process flows by opening the job or process flow in Enterprise Designer and selecting File > Expose/Unexpose and Save. 2. Open the Management Console. 3. Browse to Execution then click Scheduling. 4. Click Add to create a new schedule or, if you want to modify an existing schedule, choose the schedule and click Modify. 5. In the Add Task or Modify Task window, choose the settings for this task. • Task Name—The name you want to give to this scheduled task. This is the name that will be displayed in the task listing. • Flow type—Choose the type of process you are scheduling, either a job or a process flow. • Flow name—Select the job or process flow that you want to schedule. Only jobs and process flows that are saved and exposed are available here. If the job or process flow that you want is not shown, open the job or process flow in Enterprise Designer then select File > Expose/Unexpose and Save. • Enable task—Check this box to run the job or process flow at the specified time. Clear this box to suspend the schedule. • Schedule—Specify the date and time you want the job or process flow to run. 6. If the dataflow uses files for input or output, those files must reside on the Spectrum™ Technology Platform server or on a file server defined as an external resource in Management Console. This applies both to jobs as well as job activities within a process flow. If a source or sink stage references a file on a client-only computer, perform one of the following procedures: Option Description Option 1: Modify the dataflow Move the file to the Spectrum™ Technology Platform server or file server then modify the dataflow: 1. 2. 3. 4. Open the dataflow in Enterprise Designer. Double-click the source or sink stage. In the File name field, click the browse button. Click Remote Machine then select the file you want. Note: If you are running Enterprise Designer on the same machine as the Spectrum™ Technology Platform server, it will appear that clicking Remote Machine is no different than clicking My Computer. However, you must select the file using Remote Machine in order for the system to recognize the file as being on the Spectrum™ Technology Platform server. Option 2: Override the You can override the file references contained in the flow when this dataflow file location schedule runs. when this schedule 1. Click Options. runs 2. Under Stage file locations select the stage that references a local file. 3. Click Modify and select the file on the Spectrum™ Technology Platform server. 7. If you want the job or process flow to run on a recurring schedule, check the Task recurrence check box then click the Recurrence button and complete the fields. 8. If the dataflow has been configured for email notification, you can specify additional recipients for the notifications that will be sent when the dataflow runs. a) Click Options. b) Under Notification, click Add. c) Enter the email address you want the notification to be sent to. For example,- d) Click OK. Administration Guide 69 Jobs and Process Flows Note: Notification must be configured in Management Console in order for email notifications to work. In addition, verify that the dataflow has been configured to support notification. To do this, open the dataflow in Enterprise Designer, select Edit > Notifications. 9. Click OK. Using a File Monitor to Trigger a Job or Process Flow A file monitor triggers a job or process flow when a control file that you create is detected in a monitored directory. The presence of this control file indicates that all files required by a particular job or process flow are in place and ready for processing. When the control file appears, the file monitor runs the job or process flow you specify. File monitors are useful in cases where there are other processes that create the files you want to use as inputs to a job or process flow. 1. Open the Management Console. 2. Browse to Execution then click File Monitor. 3. Click Add. 4. In the Task name field, specify a name you wish to give to this monitor. The name can be anything you choose. 5. Check the Enable task box to turn on this file monitor. Clear the check box to disable this file monitor. 6. In the Flow type field, select the type of flow you want this monitor to run: Job Runs a batch job dataflow. Process flow Runs a process flow. 7. In the Flow name field, select the flow you want this monitor to run. 8. If the dataflow has been configured for email notification, you can specify additional recipients for the notifications that will be sent when the dataflow runs. a) Click Options. b) Under Notification, click Add. c) Enter the email address you want the notification to be sent to. For example,- d) Click OK. Note: Notification must be configured in Management Console in order for email notifications to work. In addition, verify that the dataflow has been configured to support notification. To do this, open the dataflow in Enterprise Designer, select Edit > Notifications. 9. In the File field, specify the full path and name of the control file that will trigger the dataflow. You can specify an exact file name or you can use the asterisk (*) as a wild card. For example, *.trg would trigger the dataflow when any file with a .trg extension appears in the folder. The presence of a control file is what triggers a job or process flow to run; it indicates that all files required for a particular job or process flow are in place and ready to be used in the flow. The control file can simply be a blank file; its presence alone will trigger the job or dataflow to run. However, for jobs, the control file can specify overrides to file paths configured in the Write to File or Read from File stages. To use a control file to override the file paths, specify the Read from File or Write from File stage names along with the input or output file as the last arguments like this: stagename=filename For example: Read\ from\ File=file:C:/myfile_input.txt Write\ to\ File=file:C:/myfile_output.txt 70 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution The stage name specified in the control file must match the stage label shown under the stage's icon in the dataflow. For example, if the input stage is labeled "Read From File" you would specify: Read\ From\ File=file:C:/inputfile.txt If the input stage is labeled "Illinois Customers" you would specify: Illinois\ Customers=file:C:/inputfile.txt When overriding a Read from File or Write to File location be sure to follow these protocols: • Start the path with the "file:" protocol. For example, on Windows specify "file:C:/myfile.txt" and on Unix or Linux specify "file:/testfiles/myfile.txt". • Contents of this file must be written in plain text. Specifically, the contents must use an ASCII-based ISO-8559-1 (Latin-1) compatible character encoding. • You must use forward slashes (/) in file paths, not backslahes. • Spaces in stage names need to be escaped with a backslash. • Stage names are case sensitive. Note: If multiple file monitors are configured, it is important that they each monitor unique file sets. Otherwise, the same control file may trigger multiple jobs or process flows causing unexpected behavior. For organizational purposes we recommend putting all required files and the control file in a dedicated directory. 10. In the Poll interval field, specify in seconds how often the monitor should look in the designated location for the control file. For example, if you specify 10 and a file name of AddressData.trg, the monitor will look every 10 seconds to see if AddressData.trg appears in the monitor folder. The default is 60 seconds. 11. Under Working folder, in the Folder field, specify the name of the folder in which to place the control file before running the dataflow. This prevents the flow from being kicked off a second time. 12. In the Upon completion field, specify what to do with the files in the working folder when the dataflow finishes running. Keep Leaves the files in their current location with their current name. If you select this option, the files in the working folder may be overwritten each time the file monitor runs. Move to Moves the files from the working folder to a folder you specify. Rename with time stamp Adds a time stamp to the file name in the working folder. This is the simplest way to preserve a copy of the files in the working folder for monitors that run repeatedly, since the renamed folder will have a unique name and so will not be overwritten the next time the monitor runs a dataflow. Delete Deletes the files from the working folder after the dataflow finishes running. 13. Click OK when you are done specifying the folders to monitor. Viewing Execution Status and History You can view a history of jobs and process flows in Management Console. Execution history displays information such as when dataflows and process flows ran, whether they were successful, and the number of records processed. 1. Open Management Console. 2. Expand Execution then click History. 3. Click the Jobs tab to view the history of job execution. Click the Process Flows tab to view the history of process flow execution. The Jobs tab is used to monitor job status and to pause, resume, or cancel jobs that are running as well as delete completed jobs. The Jobs tab displays the ID number, report number, job name, user, dates, job status, number of records processed, the number of records succeeded, failed, and Administration Guide 71 Jobs and Process Flows malformed, and any comments returned from the server in a grid format. This information is collected automatically. Note the following: • The Succeeded column shows the number of records that have an empty value in the Status field going to all sinks. • The Failed column shows the number of records that have a value of F in the Status field going to all sinks. • The Malformed column shows the number of records coming out of all source stage error ports. The Process Flows tab is used to monitor process flow status and to cancel process flows that are running as well as delete completed process flows. The Process Flows tab displays the ProcessID number, the ProcessFlowID name, the name of the user who started the process flow, the status of the process flow, times when the process flow started and ended, and any comments returned from the server in a grid format. This information is collected automatically. If you click the plus sign next to any given process flow, you will view Activity Status information for the process flow. The following information is included in this area: • ActivityName—includes the names of all activities, including any success activities, that make up the process flow • State—the status of the activity (whether it has completed or not) • ReturnCode—any codes that were returned when the activity ran • Started—the date and time the activity started • Finished—the date and time the activity ended • Comment—any comments associated with the activity 4. Select the fields you want displayed in the Execution History by clicking the icon just to the left of the first column. This is the Field Chooser. 5. You can group types of information together in the Execution History. Simply highlight a column name (such as ID or Name) and drag it up to the area that says, "Drag a column header here to group by that column." The information will then be grouped by that type of information. For instance, if you group by name, your Execution History might look like the following: 72 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution 6. You can sort the data in the grid by clicking the column name. Filter the data to change the list of process flows shown by doing the following: a) Click on the drop-down list next to Show only process flows where to select a variable (such as ProcessID). b) Select one of the criterion in the next drop-down (such as "greater than or equal to"). c) Type in a comparison value (such as zero) in the last box. d) Click Refresh to refresh the data. 7. The Details screen allows you to view the job definition or the process flow definition, which shows the dataflow. It also allows you to see how a dataflow was built if it's no longer accessible by Enterprise Designer. a) Click the job or process flow you wish to view then click Details.... The left pane displays the name of the job or process flow you selected and allows you to select to see the Execution Information or the flow definition. Within the Execution Information, you can select any activity within the process flow. b) Click Job/Process Flow Definition on the left pane to review the processing selections for that flow. Pausing and Resuming a Job To pause and resume a job that is running: 1. Open Management Console. 2. Expand Execution then click History. 3. Click the Jobs tab. 4. Select the job you want to pause then click Pause. 5. To resume job execution, click Resume. Canceling a Job or Process Flow 1. Open Management Console. 2. Expand Execution then click History. 3. Click the Jobs tab. 4. Select the job you want to cancel then click Cancel. Exporting Execution History You can export the information displayed in the Execution History window in Management Console to an Excel file. 1. Open Management Console. 2. Expand Execution then click History. Administration Guide 73 Transaction History 3. Click the Jobs tab if you want to export execution history for jobs. Click Process Flows if you want to export execution history for process flows. 4. Click Export and choose a location to save the exported file. Tip: If you want to export only certain records, modify the filter settings to show only those jobs or process flows whose history you want to export. Setting the Default Malformed Records Threshold You can specify how many malformed records to allow before a job stops processing. For example, if you specify 50, jobs containing 50 or more malformed records will not complete processing successfully. This procedure describes how to set a default malformed record threshold for jobs on your system. Note: You can override the default malformed record threshold for a job by opening the job in Enterprise Designer and going to Edit > Job Options. 1. Open Management Console. 2. Expand Execution then click Job Options. 3. Select one of the following: • Do not terminate the job on a malformed input record—Select this option to allow an unlimited number of malformed records in a job. • Terminate the job after reading _ malformed records—Select this option to terminate jobs if a certain number of malformed records are encountered. Enter the number of malformed records after which you want a job to stop processing. Setting Default Report Options If a job includes a report stage the job generates a report file as specified in the dataflow. Reports can include processing summaries or postal forms such as the USPS CASS 3553 form. Some modules come with predefined reports. You can also create custom reports. You can set the default report options for your system in Management Console. The default report options for your system can be overridden. In Enterprise Designer, you can override the options for a particular job, or for a particular report within a job. The following procedure describes how to set the default reporting options for your system. 1. Open Management Console. 2. Expand Execution then click Report Options. 3. Select the format to use for reports by selecting html, pdf, or txt. 4. Check the Store report snapshot box to have the system store information indicating that a report was registered as well as the actual report snapshot. 5. Check the Archive reports box if you wish to save report snapshots. In the Report archive location field, specify the location where you want to keep the archived reports. 6. Check Overwrite existing reports if you want new reports to replace previous reports. 7. Complete the naming template to reflect how you want to name your reports. Transaction History The Transaction History contains data on service usage for the date range you specify. Data is summarized and sorted by service and by user. 74 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution Viewing Transaction History 1. Open the Management Console. 2. Expand Transaction History then click Report. 3. Select a date range for your report. You can select from the following options: • All dates—includes a history report for all transactions. • Dates before and including—includes transactions up to a certain date when you enter an end date • Dates after and including—includes transactions after a certain date when you enter a start date • Dates between—includes transactions between two dates when you enter both a start date and an end date. 4. Click View Report to run and view the report. The transaction history report for the date range you specified is displayed. This report shows successes, failures, and errors for calls to each service by service and by user. 5. Click the Export button if you wish to save the report to an external file. Setting Transaction History Options 1. Open the Management Console. 2. Expand Transaction History then click Options. 3. Check the Enable transaction history tracking check box to turn on this option. All subsequent transactions with the service(s) and server will be recorded. 4. If you want to delete transactions from the log, click the drop-down box next to Clear all transaction log entries occurred on or before and enter a date (MM/DD/YYYY) or select a date from the calendar that appears below. 5. Click Clear to delete the transactions. Remote Servers If you have multiple servers running Spectrum™ Technology Platform you can distribute processing among the servers by routing the processing for a given service to another server. This feature enables users to access services available on non-local servers, reducing time for installation and maintenance of those services. It also allows users to design custom dataflows that include services installed on remote servers. When a service is routed to another server, the execution of the service will take place on the remote server, whether the services is within a dataflow, executed from Interactive Driver, or called using the Spectrum™ Technology Platform API. To determine if a service is eligible for routing, open the Management Console, click that service, and see if the Routing button at the bottom of the Options tab is enabled. Note: A real-time license is required on the remote machine to execute batch dataflows on remote server modules. Tools deployed with a particular product are available only on the machine where that product is physically installed. For example, if the Enterprise Geocoding Module is installed on both local and remote servers, the tools for that module will display only for the local server version. If you are running the Enterprise Geocoding Module only on a remote server, tools will not display at all. Adding a Remote Server Follow the steps below to add a remote server. 1. Install Spectrum™ Technology Platform on another server. This will be the remote server. For installation instructions, see the Spectrum™ Technology Platform Installation Guide. Administration Guide 75 Remote Servers 2. Open the Management Console. 3. Under System, select Remote Servers. 4. Click Add. 5. Enter the name of the remote server in the Name field (required). 6. Enter the host name or IP address of the remote server in the Host field (required). 7. Enter the port number in the Port field (required). 8. Enter a valid user name for the remote server in the User name field (required). 9. Enter a valid password for the user name you entered in the Password field (required if the server requires it). 10. In the Microbatch size field, enter the number of records passed at one time, between 1 and 99 (required). The default is 50. Entering a higher number in this field will speed up input and output but slow down data transmission. 11. Enter the number of seconds, between 1 and 99, when the connection should time out in the Timeout field (required). The default is 2. 12. Check the Use Secure Sockets Layer box if the remote server you are trying to connect to is behind a firewall with only HTTPS access. 13. If you wish to test the connection, click the Test button. If you successfully added a remote server, you will receive a message that says, "Remote server connection test successful." If the remote server test fails, you will receive a message that says, "Remote server test failed," along with the reason for the failure. If the remote server test takes longer than you would like to wait to test (which implies that the test will fail), you have the option of clicking the Stop button. 14. Click OK. 15. Click Refresh after adding or deleting a service on a remote server to update Management Console. (Conversely, when you add, modify, or delete a remote server, Management Console will refresh automatically.) Related Links Remote Servers on page 75 Troubleshooting Remote Server Errors on page 77 Routing a Service to a Remote Server The Routing button enables you to specify a different server to use for a stage or service's processing, reducing time for installation and maintenance of those services. It also allows you to design custom dataflows that include services and stages installed on remote servers. Note: You can override a service's remote server setting in Enterprise Designer or the Spectrum™ Technology Platform API. Remote server routing cannot be overridden in Interactive Driver; instead, Interactive Driver will use the remote server routing that is designated in Management Console. Follow the steps below to route a service or stage through a remote server: 1. Open the Management Console. 2. Select the service you want to route to a remote server. 3. On the Options tab, click Routing. If the Routing button is grayed out then routing is not available for this module. The Routing dialog appears. 4. Click Remote and select the remote server to which you wish to route the process for this stage. 5. Click OK. When you add a remote server that contains services or stages not also available on a local server, it brings with it the default options from that remote server. When you make changes to services or stages on a remote Management Console, those changes will not be reflected on the local server. The local Management Console will reflect its own default options. 76 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution Related Links Remote Servers on page 75 Troubleshooting Remote Server Errors on page 77 Modifying a Remote Server Follow the steps below to modify a remote server. 1. Open Management Console. 2. Under System, select the Remote Servers subnode. The Remote Servers dialog box will appear. 3. Highlight the server you want to update and click Modify. The Modify Remote Server dialog box will appear. 4. Make the appropriate changes to the server and click OK. 5. Click Refresh after adding or deleting a module on a remote server to update Management Console. (Conversely, when you add, modify, or delete a remote server, Management Console will refresh automatically.) Deleting a Remote Server Follow the steps below to delete a connection. Note: If someone else is using a dependent dataflow, you will not be able to delete the remote server. 1. Open Management Console. 2. Under System, select the Remote Servers subnode. The Remote Servers dialog box will appear. 3. Highlight the server you want to update and click Delete. 4. You will receive a confirmation message asking if you wish to delete the server. Click OK to confirm. 5. Click Refresh after adding or deleting a module on a remote server to update Management Console. (Conversely, when you add, modify, or delete a remote server, Management Console will refresh automatically.) 6. Deleting a remote server will cause any dataflows referencing that remote server to no longer function properly. If you delete a remote server that has a service or stage routed through it, you are prompted to change the routing of that service or stage. • To prevent affected services, stages, and dataflows from becoming unusable, reconfigure the order of servers, in order of preference, that you wish to replace the server being deleted and click Next. • The Verify Dataflow References dialog will appear if you have any dataflows that use the remote server you are deleting. • The Verify Service References dialog will appear if you have any services or stages that use the remote server you are deleting. • Review the information on these dialogs and change the server that the dataflows or services used. Click Finish. Troubleshooting Remote Server Errors This section discusses possible errors you may experience when using remote servers. Module Not Licensed The remote server must have a realtime license for the module to execute remote server requests. If you try to run a job but the remote server does not have a realtime license for the module, you will receive an error similar to the following: StageException: No license for stage GetCandidateAddresses on remote server myremoteserver. A realtime license is required. Administration Guide 77 Optimizing Sort Performance Remote Server Not Available If the remote server is not running or is not reachable for any other reason, the remote services will become unavailable in Enterprise Designer and Management Console. You will see a yellow hazard icon in the status bar at the bottom of the screen: Click this icon to see an error message that describes which remote servers are not available. In addition, in Enterprise Designer any stages that use a remote stage will be replaced with an icon showing you the stage is no longer available: Routing Has Changed If you delete or undeploy a service that is installed both locally and remotely and has been routed through a remote server, and then click that service within Management Console, you will see a routing change indicator (a blinking exclamation point) next to the routing button on the Options tab for that service. This indicator means the routing has changed for that service. Related Links Remote Servers on page 75 Adding a Remote Server on page 75 Routing a Service to a Remote Server on page 76 Optimizing Sort Performance Sort Performance options enable you to optimize the performance of sorting operations on large data sets. The sort performance values you specify in the Management Console can be overridden in individual stages that perform sorting operations on data. To specify sort performance settings: 1. Open the Management Console. 2. Expand Execution then click Sort Performance. 3. Use these settings to control sort performance: 78 In memory record limit Specifies the maximum number of data rows a sorter will hold in memory before it starts paging to disk. Be careful in environments where there are jobs running concurrently because increasing the In memory record limit setting increases the likelihood of running out of memory. Maximum number of temporary files to use Specifies the maximum number of temporary files that may be used by a sort process. Enable compression Specifies that temporary files are compressed when they are written to disk. Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution Note: The optimal sort performance settings depends on your server's hardware configuration. Nevertheless, the following equation generally produces good sort performance: (InMemoryRecordLimit × MaxNumberOfTempFiles ÷ 2) >= TotalNumberOfRecords Setting Default Type Conversion Options Spectrum™ Technology Platform automatically converts data to the data type needed by each stage in a dataflow. In addition, you can convert data between string and numeric or date/time data types in some stages, such as Read from File. By default, dataflows use the default data type conversion options specified in the Management Console when a data type conversion fails. You can override the default behavior for individual dataflows in Enterprise Designer if needed. To set the default type conversion options for your system, follow this procedure. 1. Open the Management Console. 2. Browse to Execution and click Type Conversion Options. 3. Choose how to handle data type conversion options by selecting one of the following options. These options specify what to do when Spectrum™ Technology Platform is unable to convert a field's data to the data type required by a stage. Fail the dataflow If a field cannot be converted the dataflow will fail. Fail the record If a field cannot be converted the record will fail but the dataflow will continue to run. Initialize the field using default values If a field cannot be converted the field's value is replaced with the value you specify here. This option is useful if you know that some records contain bad data and you want to replace the bad data with a default value. Specify a value for each data type. 4. Specify the formats that you want to use for date and time data that is converted to a string. When the data or time is converted to a string, the string will be in the format you specify here. a) In the Locale field, select the country whose format you want to use for dates converted to a string. Your selection will determine the default values in the Date, Time, and DateTime fields. Your selection will also determine the language used when a month is spelled out. For example, if you specify English the first month of the year would be "January" but if you specify French it would be "Janvier." b) In the Date field, select the format to use for date data when it is converted to a string. A list of the most commonly used formats for the selected locale is provided. For example, if you choose the format M/D/YY and a date field contains 2012-3-2, that date data would be converted to the string 3/2/12. c) In the Time field, select the format to use for time data when it is converted to a string. A list of the most commonly used formats for the selected locale is provided. For example, if you choose the format h:mm a and a time field contains 23:00, that time data would be converted to the string 11:00 PM. d) In the DateTime field, select the format to use for fields containing the DateTime data type when converted to a string. A list of the most commonly used formats for the selected locale is provided. For example, if you choose the format M/d/yy h:mm a and a DateTime field contains-:00, that DateTime data would be converted to the string 3/2/12 11:00 PM. e) In the Whole numbers field, select the formatting you want to use for whole numbers (data types float and double). For example, if you choose the format #,### then the number 4324 would be formatted as 4,324. Administration Guide 79 Setting Default Type Conversion Options Note: If you leave this field blank, numbers will be formatted in the same way they were in Spectrum™ Technology Platform 8.0 and earlier. Specifically, no thousands separator is -3 used, the dot (".") is used as the decimal separator, numbers less than 10 or greater 7 than or equal to 10 are shown in scientific notation, and negative numbers have a minus sign ("-") in front of them. Also note that if you leave this field blank, numbers that use the bigdecimal data type will always be in the format #,###.000. f) In the Decimal numbers field, select the formatting you want to use for numbers that contain a decimal value (data types integer and long). For example, if you choose the format #,##0.0# then the number 4324.25 would be formatted as 4,324.25. Note: If you leave this field blank, numbers will be formatted in the same way they were in Spectrum™ Technology Platform 8.0 and earlier. Specifically, no thousands separator is -3 used, the dot (".") is used as the decimal separator, numbers less than 10 or greater 7 than or equal to 10 are shown in scientific notation, and negative numbers have a minus sign ("-") in front of them. Also note that if you leave this field blank, numbers that use the bigdecimal data type will always be in the format #,###.000. You can also specify your own date, time, and number formats if the ones available for selection do not meet your needs. To specify your own date or time format, type the format into the field using the notation described in Date and Time Patterns on page 80. To specify your own number format, type the format into the file using the notation described in Number Patterns on page 82. Date and Time Patterns When defining data type options for date and time data, you can create your own custom date or time pattern if the predefined ones do not meet your needs. To create a date or time pattern, use the notation described in the following table. For example, this pattern: dd MMMM yyyy Would produce a date like this: 14 December 2012 80 Letter Description Example G Era designator AD yy Two-digit year 96 yyyy Four-digit year 1996 M Numeric month of the year. 7 MM Numeric month of the year. If the number is less than 10 a zero is added to make it a two-digit number. 07 MMM Short name of the month Jul MMMM Long name of the month July w Week of the year 27 ww Two-digit week of the year. If the week is less than 06 10 an extra zero is added. W Week of the month 2 D Day of the year 189 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution Letter Description DDD Three-digit day of the year. If the number contains 006 less than three digits, zeros are added. d Day of the month dd Two-digit day of the month. Numbers less than 10 09 have a zero added. F Day of the week in month 2 E Short name of the day of the week Tue EEEE Long name of the day of the week Tuesday a AM/PM marker PM H Hour of the day, with the first hour being 0 and the 0 last hour being 23. HH Two-digit hour of the day, with the first hour being 08 0 and the last hour being 23. Numbers less than 10 have a zero added. k Hour of the day, with the first hour being 1 and the 24 last hour being 24. kk Two-digit hour of the day, with the first hour being 02 1 and the last hour being 24. Numbers less than 10 have a zero added. K Hour hour of the morning (AM) or afternoon (PM), 0 with 0 being the first hour and 11 being the last hour. KK Two-digit hour of the day, with the first hour being 02 1 and the last hour being 24. Numbers less than 10 have a zero added. h Hour of the morning (AM) or afternoon (PM), with 12 1 being the first hour and 12 being the last hour. hh Two-digit hour of the morning (AM) or afternoon 09 (PM), with 1 being the first hour and 12 being the last hour. Numbers less than 10 have a zero added. m Minute of the hour mm Two-digit minutes of the hour. Numbers less than 05 10 have a zero added. s Second of the minute ss Two-digit second of the minute. Numbers less than 02 10 have a zero added. S Millisecond of the second SSS Three-digit millisecond of the second. Numbers 978 containing fewer than three digits will have one or 078 two zeros added to make them three digits. 008 z Time abbreviation of the time zone name. If the PST time zone does not have a name, the GMT offset. GMT-08:00 Administration Guide Example 10 30 55 978 81 Setting Default Type Conversion Options Letter Description Example zzzz The full time zone name. If the time zone does not Pacific Standard Time have a name, the GMT offset. GMT-08:00 Z The RFC 822 time zone. -0800 X The ISO 8601 time zone. -08Z XX The ISO 8601 time zone with minutes. -0800Z XXX The ISO 8601 time zone with minutes and a colon -08:00Z separator between hours and minutes. Related Links Setting Default Type Conversion Options on page 79 Number Patterns When defining data type options for numeric data, you can create your own custom number pattern if the predefined ones do not meet your needs. A basic number pattern consists of the following elements: • A prefix such as a currency symbol (optional) • A pattern of numbers containing an optional grouping character (for example a comma as a thousands separator) • A suffix (optional) For example, this pattern: $ ###,###.00 Would produce a number formatted like this (note the use of a thousands separator after the first three digits): $232,998.60 Patterns for Negative Numbers By default, negative numbers are formatted the same as positive numbers but have the negative sign added as a prefix. The character used for the number sign is based on the locale. The negative sign is "-" in most locales. For example, if you specify this number pattern: 0.00 The number negative ten would be formatted like this in most locales: -10.00 However, if you want to define a different prefix or suffix to use for negative numbers, specify a second pattern, separating it from the first pattern with a semicolon (";"). For example: 0.00;(0.00) In this pattern, negative numbers would be contained in parentheses: (10.00) Scientific Notation If you want to format a number into scientific notation, use the character E followed by the minimum number of digits you want to include in the exponent. For example, given this pattern: 0.###E0 The number 1234 would be formatted like this: 82 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution 1.234E3 3 In other words, 1.234 x 10 . Note the following: • The number of digit characters after the exponent character gives the minimum exponent digit count. There is no maximum. • Negative exponents are formatted using the localized minus sign, not the prefix and suffix from the pattern. • Scientific notation patterns cannot contain grouping separators (for example, a thousands separator). Special Number Pattern Characters The following characters are used to produce other characters, as opposed to being reproduced literally in the resulting number. If you want to use any of these special charters as literal characters in your number pattern's prefix or suffix, surround the special character with quotes. Symbol Description 0 Represents a digit in the pattern including zeros where needed to fill in the pattern. For example, the number twenty-seven when applied to this pattern: 0000 Would be: 0027 # Represents a digit but zeros are omitted. For example, the number twenty-seven when applied to this pattern: #### Would be: 27 . The decimal separator or monetary decimal separator used in the selected locale. For example, in the U.S. the dot (.) is used as the decimal separator but in France the comma (,) is used as the decimal separator. - The negative sign used in the selected locale. For most locals this is the minus sign (-). , The grouping character used in the selected locale. The appropriate character for the selected locale will be used. For example, in the U.S., the comma (,) is used as a separator. The grouping separator is commonly used for thousands, but in some countries it separates ten-thousands. The grouping size is a constant number of digits between the grouping characters, such as 3 for 100,000,000 or 4 for 1,0000,0000. If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer is the one that is used. For example, all the following patterns produce the same result: #,##,###,#### ######,#### ##,####,#### Administration Guide 83 Configuring Remote Component Options Symbol Description E Separates mantissa and exponent in scientific notation. You do not need to surround the E with quotes in your pattern. See Scientific Notation on page 82. ; Separates positive and negative subpatterns. See Patterns for Negative Numbers on page 82. % Multiply the number by 100 and show the number as a percentage. For example, the number .35 when applied to this pattern: ##% Would produce this result: 35% ¤ The currency symbol for the selected locale. If doubled, the international currency symbol is used. If present in a pattern, the monetary decimal separator is used instead of the decimal separator. ' Used to quote special characters in a prefix or suffix. For example: "'#'#" Formats 123 to: "#123" To create a single quote itself, use two in a row: "# o''clock" Related Links Setting Default Type Conversion Options on page 79 Configuring Remote Component Options Some remote components can be configured to maximize performance. For example, a remote component might have options controlling how much reference data is cached in memory or how incoming data is matched to the reference data. Additionally, because a remote component runs in a separate JVM, that JVM can be configured for performance without affecting the Spectrum™ Technology Platform server. Remote component options affect all instances of the component as well as any stages that use that component. This is different from stage options, which can be modified at design time and at runtime. Universal Addressing Module Component Configuration For U.S. address processing, there are several options controlling which reference data is cached in memory. These options are set in this configuration file: server/modules/c1p/java.properties. • DpvMemoryModel: Controls which DPV files are in memory Link • LacsLinkMemoryModel: Controls which LACS files are in memory Link • SuiteLinkMemoryModel: Controls which Suite files are in memory Refer to the java.properties configuration file for specifics on the different values for these options. 84 Spectrum™ Technology Platform 9.0 Chapter 5: Managing Execution Enterprise Geocoding Module Component Configuration The Enterprise Geocoding Module has several options that can affect the performance of U.S. geocoding. The options are in this configuration file: server/modules/geostan/java.properties. Of particular interest are: • egm.us.multimatch.max.records: Specifies the maximum number of possible matches to return. A smaller number results in better performance, but at the expense of matches. • egm.us.multimatch.max.processing: Specifies the number of searches to perform. A smaller number results in better performance, but at the expense of matches. • FileMemoryLimit: Controls how much of the reference data is initially loaded into memory. JVM Performance Tuning There are JVM options that will yield performance gains with certain hardware. These are advanced options and can cause unexpected behavior when used incorrectly (possibly even JVM crashes). We recommend that you contact technical support if you want to explore increasing performance by tuning the JVM. • On multiple CPU computers the -XX:+UseParallelGC option can be added to improve GC processing. • We have also seen performance increases by adding these options, although on some hardware they have been known to cause JVM crashes. • -Xmn512m • -XX:+AggressiveOpts Administration Guide 85 Monitoring Your System In this section: • • • • • • Monitoring Performance . . . . . . . . . . . . . . . . . . . . . . . . . .88 Configuring E-mail Notification . . . . . . . . . . . . . . . . . . . . .89 Configuring License Expiration Notification . . . . . . . . . .89 Event Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90 Viewing Version Information . . . . . . . . . . . . . . . . . . . . . . .91 Viewing and Exporting License Information . . . . . . . . . .91 6 Monitoring Performance Monitoring Performance The Spectrum™ Technology Platform JMX console provides a performance monitoring tool that records performance statistics for each stage in a dataflow. Use the JMX console to identify bottlenecks and observe the effects of different performance tuning adjustments. 1. Open a web browser and go to http://:/jmx-console Where: is the IP address or hostname of your Spectrum™ Technology Platform server. is the HTTP port used by Spectrum™ Technology Platform. The default is 8080. 2. Enter "admin" for both the user name and password. 3. Under " Domain: com.pb.spectrum.platform.performance", click com.pb.spectrumplatform.performance:server=PerformanceMonitorManager. 4. Click the Invoke button next to enable. 5. Click Return to MBean View to go back to the PerformanceMonitorManager screen. Performance monitoring is now enabled. When a dataflow runs, the performance statistics will display at the top of the PerformanceMonitorManager screen. Note the following: • The statistics are reported in a semicolon-delimited format. The first row is the column header. We recommend putting the data into a spreadsheet for easier viewing. • The time values in the report (Avg, Min, Max, Total) are displayed in milliseconds. • You must refresh the screen to see updates. • To reset the counters, click the Invoke button next to reset. • If you stop the Spectrum™ Technology Platform server, performance monitoring will be turned off. You will have to turn it back on when you start the server again. 88 Spectrum™ Technology Platform 9.0 Chapter 6: Monitoring Your System Configuring E-mail Notification Spectrum™ Technology Platform can alert you to potential problems to ensure that critical business processes are not interrupted. Notifications are sent as a result of conditions within dataflows and process flows. The messages can be formatted to contain context-sensitive information about the event that occurred. 1. Open the Management Console. 2. Expand System then click Notification. 3. In the Host field, enter a valid host name or IP address. 4. Enter a valid port number or range in the Port field. The default is 25. 5. Enter the user name for logging on to the SMTP server in the User Name field. 6. Enter a password for logging on to the SMTP server in the Password field. 7. If you completed the Password field, re-enter the password for logging on to the SMTP server in the Confirm Password field. 8. Enter a valid e-mail address to where notification e-mail will be sent in the From Address field. 9. Enter a valid e-mail address to where notification e-mail will be sent in the Test Address field. This is used to ensure the notification process works. 10. Click Test to send a test message. Configuring License Expiration Notification You can have Spectrum™ Technology Platform send an email notification when a license is about to expire. 1. Open the Management Console. 2. Expand System then click Notification. 3. In the Host field, enter a valid host name or IP address. 4. Enter a valid port number or range in the Port field. The default is 25. 5. Enter the user name for logging on to the SMTP server in the User Name field. 6. Enter a password for logging on to the SMTP server in the Password field. 7. If you completed the Password field, re-enter the password for logging on to the SMTP server in the Confirm Password field. 8. Enter a valid e-mail address to where notification e-mail will be sent in the From Address field. 9. Enter a valid e-mail address to where notification e-mail will be sent in the Test Address field. This is used to ensure the notification process works. 10. Click Test to send a test message. 11. Click the Expiration Settings tab. 12. In the Days before expiration to send notification field, specify the number of days in advance that you want to be notified of a pending license or data expiration. For example, if you want to be notified 30 days before a license expires, specify 30. 13. Check the Send expiration notification check box. 14. Click Add and specify the email address you want to receive the notification. 15. Select File > Save. Administration Guide 89 Event Log Event Log Viewing the Event Log The event log displays messages from the Spectrum™ Technology Platform server's wrapper log. The event log contains information about server operations as well as requests made to services from the API and through web services. Use the event log when you experience trouble and are looking for information about possible causes. 1. Open the Management Console. 2. Expand Event Log then click Events. 3. Click Refresh to view the latest entries. 4. Check Show events upon open to automatically load the event log. If you do not check this option you must click the Refresh button to view the latest information. You can also view the event log by using a text editor and opening the file \server\app\repository\logs\wrapper.log. Setting Event Log Options You can specify the default logging level as well as logging levels for each service on your system. When you change logging levels the change will not be reflected in the log entries made before the change. 1. Open the Management Console. 2. Expand Event Log then click Options. 3. Click the System default logging level drop-down list to select an event logging level. Event logging levels include the following: • Disabled—no event logging enabled. • Fatal—minimal logging, logs only fatal errors. Fatal errors are those that make the system unusable. • Error—logs only errors and fatal errors. Errors make a single call unusable, possibly a single service, but not the whole system. The inability to load a specific service might be an error since other services would be available. • Warn—event warnings and errors are logged. Warnings indicate problems that do not stop the system from working (for example, when loading a service where a parameter has an invalid value, a warning is issued and the default parameter is used). During the use of a service, if results are returned but there is a problem, a warning will be logged. An example might be that casing was set to lower case, but Canadian does not support casing. Results are returned with a warning that the casing option was ignored. • Info—logging of high-level system information. This is the most detailed logging level suitable for production. Info level will typically be used during startup and initialization, providing product and version information, which services were loaded, etc. • Debug—a highly detailed level of logging, suitable for debugging problems with the system. • Trace—the most detailed level of logging, tracing program execution (method entry and exit). It provides detailed program flow information for debugging. Each logging level includes the ones above it on the list. In other words, if Warning is selected as the logging level, errors and fatal errors will also be logged. If Info is selected, informational messages, warnings, errors, and fatal errors will be logged. Note: Selecting the most intensive logging level can affect system performance. Therefore, you should select the least intensive setting that meets your particular logging requirements. 4. If you want to specify different logging levels for each service choose the logging level you want. 90 Spectrum™ Technology Platform 9.0 Chapter 6: Monitoring Your System Viewing Version Information 1. In Management Console, expand System then click Version Information. 2. The Version Information window presents information on the configured services. Expanding the Server Information, System Information, Service Information, and Component Information folders will present the corresponding details. This includes versions numbers of the server, the operating system, the service software, and component versions. Note: This information is view-only. Viewing and Exporting License Information 1. Open the Management Console. 2. Expand System then click Licensing. 3. Click the Expiration Info tab to view a list of licenses that are about to expire. Only licenses that are within the period specified on in the Notification node, Expiration Settings tab, are displayed. 4. Click the License Information tab to view a complete listing of all licenses installed on your system. To export your license information to a .lic file, click Export. This is helpful when resolving license issues with technical support. Administration Guide 91 About Spectrum Technology Platform In this section: • • • • What Is Spectrum™ Technology Platform? . . . . . . . . . . .94 Enterprise Data Management Architecture . . . . . . . . . . .95 Spectrum™ Technology Platform Architecture . . . . . . . .98 Modules and Components . . . . . . . . . . . . . . . . . . . . . . . .101 7 What Is Spectrum™ Technology Platform? What Is Spectrum™ Technology Platform? Spectrum™ Technology Platform is a system that improves the completeness, validity, consistency, timeliness, and accuracy of your data through data standardization, verification and enhancement. Ensuring that your data is accurate, complete, and up to date enables your firm to better understand and connect with your customers. Note: For more information on Spectrum™ Technology Platform, please visit the Spectrum™ Technology Platform Video Tutorials site. Spectrum™ Technology Platform aids in the design and implementation of business rules for data quality by performing the following functions. Parsing, Name Standardization, and Name Validation To perform the most accurate standardization you may need to break up strings of data into multiple fields. Spectrum™ Technology Platform provides advanced parsing features that enable you to parse personal names, company names, and many other terms and abbreviations. In addition, you can create your own list of custom terms to use as the basis of scan/extract operations. The Universal Name Module provides this functionality. Deduplication and Consolidation Identifying unique entities enables you to consolidate records, eliminate duplicates and develop "best-of-breed" records. A "best-of-breed" record is a composite record that is built using data from other records. The Advanced Matching Module and Data Normalization Module provide this functionality. Address Validation Address validation applies rules from the appropriate postal authority to put an address into a standard form and even validate that the address is a deliverable address. Address validation can help you qualify for postal discounts and can improve the deliverability of your mail. The Universal Addressing Module and the Address Now Module provide this functionality. Geocoding Geocoding is the process of taking an address and determining its geographic coordinates (latitude and longitude). Geocoding can be used for map generation, but that is only one application. The underlying location data can help drive business decisions. Reversing the process, you can enter a geocode (a point represented by a latitude and longitude coordinate) and receive address information about the geocode. The Enterprise Geocoding Module provides this functionality. Location Intelligence Location intelligence creates new information about your data by assessing, evaluating, analyzing and modeling geographic relationships. Using location intelligence processing you can verify locations and transform information into valuable business intelligence. The Location Intelligence Module provides this functionality. Master Data Management Master data management enables you to create relationship-centric master data views of your critical data assets. The Data Hub Module helps you identify influencers and non-obvious relationships, detect fraud, and improve the quality, integration, and accessibility of your information. 94 Spectrum™ Technology Platform 9.0 Chapter 7: About Spectrum Technology Platform Tax Jurisdiction Assignment Tax jurisdiction assignment takes an address and determines the tax jurisdictions that apply to the address's location. Assigning the most accurate tax jurisdictions can reduce financial risk and regulatory liability. Spectrum™ Technology Platform software from Pitney Bowes Software integrates up-to-date jurisdictional boundaries with the exact street addresses of your customer records, enabling you to append the correct state, county, township, municipal, and special tax district information to your records. Some example uses of tax jurisdiction assignment are: • Sales and use tax • Personal property tax • Insurance premium tax The Enterprise Tax Module provides this functionality. Enterprise Data Management Architecture With Spectrum™ Technology Platform, you can build a comprehensive enterprise data management process, or you can target those individual areas in which your company needs improvement. The following diagram illustrates a complete solution that takes data from its source, through data enrichment and data quality processes, feeding a master data management hub which makes a single view of the data available to multiple business applications. Administration Guide 95 Enterprise Data Management Architecture Data Discovery Data discovery is the process of scanning your data resources to get a complete inventory of your data landscape. Spectrum™ Technology Platform can scan structured data, unstructured data, and semi-structured data using a wide array of data profiling techniques. The results of the scan are used to automatically generate a library of documentation describing your company's data assets and to create a metadata repository. This documentation and accompanying metadata repository provide the insight you need before beginning data integration, data quality, data governance, or master data management projects. For more information on the Spectrum™ Technology Platform Data Discovery Module, contact your account executive. Data Integration Once you have an inventory of your data landscape, you need to consider how you will access the data you need to manage. Spectrum™ Technology Platform can connect to data in multiple sources either directly or through integration with your existing data access technologies. It supports batch and real time data integration capabilities for a variety of business needs including data warehousing, data quality, 96 Spectrum™ Technology Platform 9.0 Chapter 7: About Spectrum Technology Platform systems integration, and migration. Spectrum™ Technology Platform can access data in RDBMS databases, data warehouses, XML files, flat files, and variable format files. Spectrum™ Technology Platform supports SQL queries with complex joins and aggregations and provides a visual query development tool. In addition, Spectrum™ Technology Platform can access data over REST and SOAP web services. Spectrum™ Technology Platform can trigger batch processing based on the appearance of one or more source files in a specified folder. This "hot folder" trigger is useful for monitoring FTP uploads and processing them as they occur. Some of these data integration capabilities require a license for the Enterprise Data Integration Module. For more information, contact your account executive. Finally, Spectrum™ Technology Platform can integrate with packaged applications such as SAP and Siebel. Data Quality/Governance Data quality and data governance processes check your data for duplicate records, inconsistent information, and inaccurate information. Duplicate matching identifies potential duplicate records or relationships between records, whether the data is name and address in nature or any other type of customer information. Spectrum™ Technology Platform allows you to specify a consistent set of business match rules using boolean matching methods, scoring methods, thresholds, algorithms and weights to determine if a group of records contains duplicates. Spectrum™ Technology Platform supports extensive customization so you can tailor the rules to the unique needs of your business. Once duplicate records have been identified, you may wish to consolidate records. Spectrum™ Technology Platform allows you to specify how to link or merge duplicate records so you can create the most accurate and complete record from any collection of customer information. For example, a single best-of-breed record can be built from all of the records in a household. The Advanced Matching Module is used to identify duplicates and eliminate them. Data quality processes also standardize your data. Standardization is a critical process because standardized data elements are necessary to achieve the highest possible results for matching and identifying relationships between records. While several modules perform standardization of one type or another, the Spectrum™ Technology Platform Data Normalization module provides the most comprehensive set of standardization features. In addition, the Universal Name module provides specific data quality features for handling personal name and business name data. Standardized data is not necessarily accurate data. Spectrum™ Technology Platform can compare your data to known, up-to-date reference data for correctness. The sources used for this process may include regulatory bodies such as the U.S. Postal Service, third-party data providers such as Experian or D&B, or your company's internal reference sources, such as accounting data. Spectrum™ Technology Platform is particularly strong in address data validation. It can validate or standardize addresses in 250 countries and territories around the world. There are two modules that perform address validation: the Address Now Module and the Universal Addressing Module. To determine which one is right for you, discuss your needs with your account executive. While Spectrum™ Technology Platform can automatically handle a wide range of data quality issues, there are some situations where a manual review by a data steward is appropriate. To support this, the Business Steward Module provides a way to specify the rules that will trigger a manual review, and it provides a web-based tool for reviewing exception records. It includes integrated access to third-party tools such as Bing maps and Experian data to aid data stewards in the review and resolution process. Data Enrichment Data enrichment processes augment your data with additional information. Enrichment can be based on spatial data, marketing data, or data from other sources that you wish to use to add additional detail to your data. For example, if you have a database of customer addresses, you could geocode the address to determine the latitude/longitude coordinates of the address and store those coordinates as part of the Administration Guide 97 Spectrum™ Technology Platform Architecture record. Your customer data could then be used to perform a variety of spatial calculations, such as finding the bank branch nearest the customer. Spectrum™ Technology Platform allows you to enrich your data with a variety of information, including geocoding (with the Enterprise Geocoding Module), tax jurisdiction assignment (with the Enterprise Tax Module), geospatial calculations (with the Location Intelligence Module), and driving and walking directions between points (with the Enterprise Routing Module). Master Data Management Hub The Master Data Management (MDM) hub allows for rapid modeling of entities and their complex relationships across roles, processes and interactions. It provides built-in social network analysis capabilities to help you understand influencers, predict churn, detect non-obvious relationships and fraudulent patterns, and provide recommendations. Spectrum™ Technology Platform supports two approaches to the MDM hub. In the master hub approach, the data is maintained in a single MDM database and applications access the data from the MDM database. In the registry approach, the data is maintained in each business application and the MDM hub registry contains keys which are used to find related records. For example, a customer's record may exist in an order entry database and a customer support database. The MDM registry would contain a single key which could be used to access the customer data in both places. The Data Hub Module provides MDM capabilities. Spectrum™ Technology Platform Architecture Spectrum™ Technology Platform software from Pitney Bowes Software includes a server that supports a number of modules. These modules provide different functions, such as address validation, geocoding, and advanced parsing, among others. The following diagram illustrates the Spectrum™ Technology Platform architecture. 98 Spectrum™ Technology Platform 9.0 Chapter 7: About Spectrum Technology Platform Server The foundation of the Spectrum™ Technology Platform is the server. The server handles data processing, synchronizes repository data, and manages communication between the client and the transformation modules via TCP/IP. It provides job management and security features. Modules Modules are sets of features that perform a specific function. For example, if you want to standardize your customers' addresses to conform to USPS standards, you would license the Universal Addressing module. If you want to determine the tax jurisdictions that apply to each of your customers, you would license the Enterprise Tax module. You can license just one module or multiple modules, depending on your specific needs. Most modules consist of "components" and databases. Components A component is a basic building block in a customer data quality process. Each component performs a specific function. For example, the Enterprise Geocoding module's Geocode US Address component takes an address and returns the latitude and longitude coordinates for that address; the Universal Addressing module's Get City State Province takes a postal code and returns the city and state/province where that postal code is located. Some components must first be combined with other components into a job, service, or subflow before they can be executed. Use Enterprise Designer to create jobs, services, subflows, and process flows. For more information, see Enterprise Designer on page 100. The components that you have available on your system depend on which Spectrum™ Technology Platform modules you have licensed from Pitney Bowes Software. Administration Guide 99 Spectrum™ Technology Platform Architecture Databases Modules often include databases that contain the data needed by the components in the module. For example, the Universal Addressing module needs to have access to USPS data in order to verify and standardize addresses. So, the Universal Addressing module comes with the U.S. Postal Database, which you must load into a location that is accessible by your Spectrum™ Technology Platform system. Modules have both required and optional databases. Optional databases provide data needed for certain features that can greatly enhance your Spectrum™ Technology Platform process. Management Console The Management Console is a Windows-based tool for administering Spectrum™ Technology Platform. You can use the Management Console to: • • • • • Specify a server access address Select component access method (local or hosted) Specify the default settings for Spectrum™ Technology Platform components Manage user accounts, including permissions and passwords Set up logging, tracking, and reporting. Enterprise Designer Enterprise Designer is a Windows-based tool for creating Spectrum™ Technology Platform jobs, services, subflows, and process flows. It utilizes an easy drag-and-drop interface to allow you to graphically create complex dataflows. 100 Spectrum™ Technology Platform 9.0 Chapter 7: About Spectrum Technology Platform API The Spectrum™ Technology Platform API, which is provided in the Spectrum™ Technology Platform Client API, is designed to provide simple integration, streamline record processing, and support backward compatibility of future versions. The Spectrum™ Technology Platform API can be accessed through: • • • • • • C C++ COM Java .NET Web services Modules and Components Table 2: Modules, Components, and Databases Module Description Components Address Now Module Provides enhanced validation and standardization for addresses outside the U.S., and other address processing. Build Global Address Get Global Candidate Addresses Validate Global Address Advanced Matching Module Administration Guide Matches records within and/or between input Best Of Breed files. 101 Modules and Components Module Description Components Candidate Finder Duplicate Synchronization Filter Interflow Match Intraflow Match Match Key Generator Transactional Match Business Steward Module Identifies exception records and provides a browser-based tool for manually reviewing exception records. Exception Monitor Read Exceptions Write Exceptions Country Identifier Takes a country name or a combination of Country Identifier postal code and state/province and returns the two-character ISO country code, the three-character Universal Postal Union (UPU) code, and the English country name. Data Hub Module Links and analyzes data, identifying relationships and trends. Write to Hub Read From Hub Query Hub Graph Visualization Data Integration Module Provides capabilities useful in data warehousing, data quality, systems integration, and migration. Field Selector Generate Time Dimension Query Cache Write to Cache Data Normalization Module Removes inconsistencies in data. Advanced Transformer Open Parser Table Lookup Transliterator Enterprise Data Integration Connects to data in multiple sources for a variety of business needs including data warehousing, data quality, systems integration, and migration. Call Stored Procedure Field Selector Generate Time Dimension Query Cache Write to Cache Enterprise Geocoding Module Determines the geographic coordinates for an address. Also determines the address of a given latitude and longitude. Geocode Address AUS Geocode Address GBR Geocode Address Global Geocode Address World Geocode US Address GNAF PID Location Search Reverse APN Lookup Reverse Geocode Address Global 102 Spectrum™ Technology Platform 9.0 Chapter 7: About Spectrum Technology Platform Module Description Components Reverse Geocode US Location Enterprise Routing Module Obtains driving or walking directions, Get Travel Boundary calculates drive time and drive distance, and Get Travel Cost Matrix identifies locations within a certain time or distance from a starting point. Get Travel Directions Enterprise Tax Module Determines the tax jurisdictions that apply to Assign GeoTAX Info a given location. Calculate Distance GeoConfidence Module Determines the probability that an address or Geo Confidence Surface street intersection is within a given area. CreatePointsConvexHull Global Sentry Attempts to match transactions against Global Sentry government-provided watch lists that contain Global Sentry Address Check data from different countries. Global Sentry ID Number Check Global Sentry Name Check Global Sentry Other Data Check Location Intelligence Module Performs point in polygon and radial analysis Closest Site against a variety of geospatial databases. Find Nearest Point In Polygon Query Spatial Data Read Spatial Data Spatial Calculator Spatial Union SAP Module Enables Spectrum™ Technology Platform to SAP Generate Match Key interface with SAP Customer Relationship SAP Generate Match Score Management Module applications. SAP Generate Search Key SAP Generate Search Key Constant SAP Generate Search Key Metaphone SAP Generate Search Key Substring SAP Validate Address With Candidates Siebel Module Enables Spectrum™ Technology Platform to Siebel Generate Match Key interface Siebel applications. Siebel Generate Match Score Siebel Generate Search Key Siebel Business Name Standardization Siebel Standardize Name Siebel Geocode US Address With Candidates Administration Guide 103 Modules and Components Module Description Components Siebel Geocode US Address With No Candidates Siebel Get Global Candidate Addresses Siebel Validate Address With Candidates Siebel Validate Address With No Candidates Universal Addressing Module Standardizes and validates addresses Get Candidate Addresses according to the postal authority's standards. Get City State Province Get Postal Codes Validate Address Validate Address AUS Validate Address Global Universal Name Module Parses personal names, company names, addresses, and many other terms and abbreviations. Name Parser (Deprecated) Name Variant Finder Open Name Parser 104 Spectrum™ Technology Platform 9.0 Appendix In this section: • Country ISO Codes and Module Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Country ISO Codes and Module Support In this section: • Country ISO Codes and Module Support . . . . . . . . . . . .108 A Country ISO Codes and Module Support Country ISO Codes and Module Support The following table lists the ISO codes for each country as well as the modules that support addressing, geocoding, and routing for each country. 1 108 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Afghanistan AF AFG Address Now Module Universal Addressing Module Aland Islands AX ALA Address Now Module Universal Addressing Module Albania AL ALB Address Now Module Universal Addressing Module Algeria DZ DZA Address Now Module Universal Addressing Module American Samoa AS ASM Address Now Module Universal Addressing Module Andorra AD AND Address Now Module 1 Enterprise Geocoding Module Universal Addressing Module Angola AO AGO Address Now Module Enterprise Geocoding Module Universal Addressing Module Anguilla AI AIA Address Now Module Universal Addressing Module Antarctica AQ ATA Address Now Module Universal Addressing Module Antigua And Barbuda AG ATG Address Now Module Universal Addressing Module Argentina AR ARG Address Now Module Enterprise Geocoding Module Universal Addressing Module Armenia AM ARM Address Now Module Universal Addressing Module Aruba AW ABW Address Now Module Universal Addressing Module Australia AU AUS Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Andorra is covered by the Spain geocoder Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Austria AT AUT Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Azerbaijan AZ AZE Address Now Module Universal Addressing Module Bahamas BS BHS Address Now Module Enterprise Geocoding Module Universal Addressing Module Bahrain BH BHR Address Now Module Universal Addressing Module Bangladesh BD BGD Address Now Module Universal Addressing Module Barbados BB BRB Address Now Module Universal Addressing Module Belarus BY BLR Address Now Module Universal Addressing Module Belgium BE BEL Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Belize BZ BLZ Address Now Module Universal Addressing Module Benin BJ BEN Address Now Module Enterprise Geocoding Module Universal Addressing Module Bermuda BM BMU Address Now Module Universal Addressing Module Bhutan BT BTN Address Now Module Universal Addressing Module Bolivia, Plurinational State Of BO BOL Address Now Module Universal Addressing Module Bonaire, Saint Eustatius And BQ Saba BES Address Now Module Universal Addressing Module Bosnia And Herzegovina BA BIH Address Now Module Universal Addressing Module Botswana BW BWA Address Now Module Enterprise Geocoding Module Universal Addressing Module Administration Guide 109 Country ISO Codes and Module Support 110 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Bouvet Island BV BVT Address Now Module Universal Addressing Module Brazil BR BRA Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module British Indian Ocean Territory IO IOT Address Now Module Universal Addressing Module Brunei Darussalam BN BRN Address Now Module Universal Addressing Module Bulgaria BG BGR Address Now Module Universal Addressing Module Burkina Faso BF BFA Address Now Module Enterprise Geocoding Module Universal Addressing Module Burundi BI BDI Address Now Module Enterprise Geocoding Module Universal Addressing Module Cambodia KH KHM Address Now Module Universal Addressing Module Cameroon CM CMR Address Now Module Enterprise Geocoding Module Universal Addressing Module Canada CA CAN Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Cape Verde CV CPV Address Now Module Universal Addressing Module Cayman Islands KY CYM Address Now Module Universal Addressing Module Central African Republic CF CAF Address Now Module Universal Addressing Module Chad TD TCD Address Now Module Universal Addressing Module Chile CL CHL Address Now Module Enterprise Geocoding Module Universal Addressing Module Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules China CN CHN Address Now Module Enterprise Geocoding Module Universal Addressing Module Christmas Island CX CXR Address Now Module Universal Addressing Module Cocos (Keeling) Islands CC CCK Address Now Module Universal Addressing Module Colombia CO COL Address Now Module Universal Addressing Module Comoros KM COM Address Now Module Universal Addressing Module Congo CG COG Address Now Module Enterprise Geocoding Module Universal Addressing Module Congo, The Democratic Republic Of The CD COD Address Now Module Enterprise Geocoding Module Universal Addressing Module Cook Islands CK COK Address Now Module Universal Addressing Module Costa Rica CR CRI Address Now Module Universal Addressing Module Côte d'Ivoire CI CIV Address Now Module Universal Addressing Module Croatia HR HRV Address Now Module Enterprise Geocoding Module Universal Addressing Module Cuba CU CUB Address Now Module Universal Addressing Module Curacao CW CUW Address Now Module Universal Addressing Module Cyprus CY CYP Address Now Module Universal Addressing Module Czech Republic CZ CZE Address Now Module Enterprise Geocoding Module Universal Addressing Module Denmark DK DNK Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Administration Guide 111 Country ISO Codes and Module Support 2 112 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Djibouti DJ DJI Address Now Module Universal Addressing Module Dominica DM DMA Address Now Module Universal Addressing Module Dominican Republic DO DOM Address Now Module Universal Addressing Module Ecuador EC ECU Address Now Module Universal Addressing Module Egypt EG EGY Address Now Module Universal Addressing Module El Salvador SV SLV Address Now Module Universal Addressing Module Equatorial Guinea GQ GNQ Address Now Module Universal Addressing Module Eritrea ER ERI Address Now Module Universal Addressing Module Estonia EE EST Address Now Module Enterprise Geocoding Module Universal Addressing Module Ethiopia ET ETH Address Now Module Universal Addressing Module Falkland Islands (Malvinas) FK FLK Address Now Module Universal Addressing Module Faroe Islands FO FRO Address Now Module Universal Addressing Module Fiji FJ FJI Address Now Module Universal Addressing Module Finland FI FIN Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module France FR FRA Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module French Guiana GF GUF Address Now Module 2 Enterprise Geocoding Module Universal Addressing Module French Guiana is covered by the France geocoder Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support 3 4 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules French Polynesia PF PYF Address Now Module Universal Addressing Module French Southern Territories TF ATF Address Now Module Universal Addressing Module Gabon GA GAB Address Now Module Enterprise Geocoding Module Universal Addressing Module Gambia GM GMB Address Now Module Universal Addressing Module Georgia GE GEO Address Now Module Universal Addressing Module Germany DE DEU Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Ghana GH GHA Address Now Module Enterprise Geocoding Module Universal Addressing Module Gibraltar GI GIB Address Now Module 3 Enterprise Geocoding Module Universal Addressing Module Greece GR GRC Address Now Module Enterprise Geocoding Module Universal Addressing Module Greenland GL GRL Address Now Module Universal Addressing Module Grenada GD GRD Address Now Module Universal Addressing Module Guadeloupe GP GLP Address Now Module 4 Enterprise Geocoding Module Universal Addressing Module Guam GU GUM Address Now Module Universal Addressing Module Guatemala GT GTM Address Now Module Universal Addressing Module Guernsey GG GGY Address Now Module Universal Addressing Module Gibraltar is covered by the Spain geocoder Guadeloupe is covered by the France geocode Administration Guide 113 Country ISO Codes and Module Support 5 114 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Guinea GN GIN Address Now Module Universal Addressing Module Guinea-Bissau GW GNB Address Now Module Universal Addressing Module Guyana GY GUY Address Now Module Universal Addressing Module Haiti HT HTI Address Now Module Universal Addressing Module Heard Island and McDonald Islands HM HMD Address Now Module Universal Addressing Module Holy See (Vatican City State) VA VAT Address Now Module 5 Enterprise Geocoding Module Universal Addressing Module Honduras HN HND Address Now Module Universal Addressing Module Hong Kong HK HKG Address Now Module Enterprise Geocoding Module Universal Addressing Module Hungary HU HUN Address Now Module Enterprise Geocoding Module Universal Addressing Module Iceland IS ISL Address Now Module Universal Addressing Module India IN IND Address Now Module Enterprise Geocoding Module Universal Addressing Module Indonesia ID IDN Address Now Module Enterprise Geocoding Module Universal Addressing Module Iran, Islamic Republic Of IR IRN Address Now Module Universal Addressing Module Iraq IQ IRQ Address Now Module Universal Addressing Module Ireland IE IRL Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module The Vatican is covered by the Italy geocoder Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Isle Of Man IM IMN Address Now Module Universal Addressing Module Israel IL ISR Address Now Module Universal Addressing Module Italy IT ITA Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Jamaica JM JAM Address Now Module Universal Addressing Module Japan JP JPN Address Now Module Enterprise Geocoding Module Universal Addressing Module Jersey JE JEY Address Now Module Universal Addressing Module Jordan JO JOR Address Now Module Universal Addressing Module Kazakhstan KZ KAZ Address Now Module Universal Addressing Module Kenya KE KEN Address Now Module Enterprise Geocoding Module Universal Addressing Module Kiribati KI KIR Address Now Module Universal Addressing Module Korea, Democratic People's Republic Of KP PRK Address Now Module Universal Addressing Module Korea, Republic Of KR KOR Address Now Module Universal Addressing Module Kosovo KS KOS Address Now Module Universal Addressing Module Kuwait KW KWT Address Now Module Universal Addressing Module Kyrgyzstan KG KGZ Address Now Module Universal Addressing Module Lao People's Democratic Republic LA LAO Address Now Module Universal Addressing Module Latvia LV LVA Address Now Module Enterprise Geocoding Module Universal Addressing Module Administration Guide 115 Country ISO Codes and Module Support 6 7 116 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Lebanon LB LBN Address Now Module Universal Addressing Module Lesotho LS LSO Address Now Module Enterprise Geocoding Module Universal Addressing Module Liberia LR LBR Address Now Module Universal Addressing Module Libyan Arab Jamahiriya LY LBY Address Now Module Universal Addressing Module Liechtenstein LI LIE Address Now Module 6 Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Lithuania LT LTU Address Now Module Enterprise Geocoding Module Universal Addressing Module Luxembourg LU LUX Address Now Module 7 Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Macao MO MAC Address Now Module Enterprise Geocoding Module Universal Addressing Module Macedonia, Former Yugoslav MK Republic Of MKD Address Now Module Universal Addressing Module Madagascar MG MDG Address Now Module Universal Addressing Module Malawi MW MWI Address Now Module Universal Addressing Module Malaysia MY MYS Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Maldives MV MDV Address Now Module Universal Addressing Module Mali ML MLI Address Now Module Enterprise Geocoding Module Universal Addressing Module Liechtenstein is covered by the Switzerland geocoder Luxembourg is covered by the Belgium geocoder Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support 8 9 10 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Malta ML MLT Address Now Module Universal Addressing Module Marshall Islands MH MHL Address Now Module Universal Addressing Module Martinique MQ MTQ Address Now Module Enterprise Geocoding Module Guadeloupe is covered by the France geocode Universal Addressing Module Mauritania MR MRT Address Now Module Universal Addressing Module Mauritius MU MUS Address Now Module Universal Addressing Module Mayotte YT MYT Address Now Module Enterprise Geocoding Module Universal Addressing Module Mexico MX MEX Address Now Module Enterprise Geocoding Module Universal Addressing Module Micronesia, Federated States FM Of FSM Address Now Module Universal Addressing Module Moldova, Republic Of MD MDA Address Now Module Universal Addressing Module Monaco MC MCO Address Now Module Enterprise Geocoding Module 10 Universal Addressing Module Mongolia MN MNG Address Now Module Universal Addressing Module Montenegro ME MNE Address Now Module Universal Addressing Module Montserrat MS MSR Address Now Module Universal Addressing Module Morocco MA MAR Address Now Module Enterprise Geocoding Module Universal Addressing Module Mozambique MZ MOZ Address Now Module Enterprise Geocoding Module Universal Addressing Module Martinique is covered by the France geocoder. Mayotte is covered by the France geocoder. Monaco is covered by the France geocoder Administration Guide 117 Country ISO Codes and Module Support 118 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Myanmar MM MMR Address Now Module Universal Addressing Module Namibia NA NAM Address Now Module Enterprise Geocoding Module Universal Addressing Module Nauru NR NRU Address Now Module Universal Addressing Module Nepal NP NPL Address Now Module Universal Addressing Module Netherlands NL NLD Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module New Caledonia NC NCL Address Now Module Universal Addressing Module New Zealand NZ NZL Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Nicaragua NI NIC Address Now Module Universal Addressing Module Niger NE NER Address Now Module Enterprise Geocoding Module Universal Addressing Module Nigeria NG NGA Address Now Module Enterprise Geocoding Module Universal Addressing Module Niue NU NIU Address Now Module Universal Addressing Module Norfolk Island NF NFK Address Now Module Universal Addressing Module Northern Mariana Islands MP MNP Address Now Module Universal Addressing Module Norway NO NOR Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Oman OM OMN Address Now Module Universal Addressing Module Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support 11 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Pakistan PK PAK Address Now Module Universal Addressing Module Palau PW PLW Address Now Module Universal Addressing Module Palestinian Territory, Occupied PS PSE Address Now Module Universal Addressing Module Panama PA PAN Address Now Module Universal Addressing Module Papua New Guinea PG PNG Address Now Module Universal Addressing Module Paraguay PY PRY Address Now Module Universal Addressing Module Peru PE PER Address Now Module Universal Addressing Module Philippines PH PHL Address Now Module Enterprise Geocoding Module Universal Addressing Module Pitcairn PN PCN Address Now Module Universal Addressing Module Poland PL POL Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Portugal PT PRT Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Puerto Rico PR PRI Address Now Module Universal Addressing Module Qatar QA QAT Address Now Module Universal Addressing Module Reunion RE REU Address Now Module Enterprise Geocoding Module 11 Universal Addressing Module Romania RO ROU Address Now Module Universal Addressing Module Reunion is covered by the France geocoder Administration Guide 119 Country ISO Codes and Module Support 12 120 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Russian Federation RU RUS Address Now Module Enterprise Geocoding Module Universal Addressing Module Rwanda RW RWA Address Now Module Enterprise Geocoding Module Universal Addressing Module Saint Barthelemy BL BLM Address Now Module Universal Addressing Module Saint Helena, Ascension & Tristan Da Cunha SH SHE Address Now Module Universal Addressing Module Saint Kitts and Nevis KN KNA Address Now Module Universal Addressing Module Saint Lucia LC LCA Address Now Module Universal Addressing Module Saint Martin (French Part) MF MAF Address Now Module Universal Addressing Module Saint Pierre and Miquelon PM SPM Address Now Module Universal Addressing Module Saint Vincent And The Grenadines VC VCT Address Now Module Universal Addressing Module Samoa WS WSM Address Now Module Universal Addressing Module San Marino SM SMR Address Now Module 12 Enterprise Geocoding Module Universal Addressing Module Sao Tome And Principe ST STP Address Now Module Universal Addressing Module Saudi Arabia SA SAU Address Now Module Universal Addressing Module Senegal SN SEN Address Now Module Enterprise Geocoding Module Universal Addressing Module Serbia RS SRB Address Now Module Universal Addressing Module Seychelles SC SYC Address Now Module Universal Addressing Module San Marino is covered by the Italy geocoder Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Sierra Leone SL SLE Address Now Module Universal Addressing Module Singapore SG SGP Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Sint Maarten (Dutch Part) SX SXM Universal Addressing Module Slovakia SK SVK Address Now Module Enterprise Geocoding Module Universal Addressing Module Slovenia SI SVN Address Now Module Enterprise Geocoding Module Universal Addressing Module Solomon Islands SB SLB Address Now Module Universal Addressing Module Somalia SO SOM Address Now Module Universal Addressing Module South Africa ZA ZAF Address Now Module Enterprise Geocoding Module Universal Addressing Module South Georgia And The South GS Sandwich Islands SGS Address Now Module Enterprise Geocoding Module Universal Addressing Module South Sudan SS SSD Address Now Module Universal Addressing Module Spain ES ESP Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Sri Lanka LK LKA Address Now Module Universal Addressing Module Sudan SD SDN Address Now Module Universal Addressing Module Suriname SR SUR Address Now Module Universal Addressing Module Svalbard And Jan Mayen SJ SJM Address Now Module Universal Addressing Module Swaziland SZ SWZ Address Now Module Enterprise Geocoding Module Universal Addressing Module Administration Guide 121 Country ISO Codes and Module Support 122 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Sweden SE SWE Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Switzerland CH CHE Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Syrian Arab Republic SY SYR Address Now Module Universal Addressing Module Taiwan, Province of China TW TWN Address Now Module Universal Addressing Module Tajikistan TJ TJK Address Now Module Universal Addressing Module Tanzania, United Republic Of TZ TZA Address Now Module Enterprise Geocoding Module Universal Addressing Module Thailand TH THA Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module Timor-Leste TL TLS Address Now Module Universal Addressing Module Togo TG TGO Address Now Module Enterprise Geocoding Module Universal Addressing Module Tokelau TK TKL Address Now Module Universal Addressing Module Tonga TO TON Address Now Module Universal Addressing Module Trinidad and Tobago TT TTO Address Now Module Universal Addressing Module Tunisia TN TUN Address Now Module Enterprise Geocoding Module Universal Addressing Module Turkey TR TUR Address Now Module Enterprise Geocoding Module Universal Addressing Module Turkmenistan TM TKM Address Now Module Universal Addressing Module Spectrum™ Technology Platform 9.0 Appendix A: Country ISO Codes and Module Support ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Turks And Caicos Islands TC TCA Address Now Module Universal Addressing Module Tuvalu TV TUV Address Now Module Universal Addressing Module Uganda UG UGA Address Now Module Enterprise Geocoding Module Universal Addressing Module Ukraine UA UKR Address Now Module Enterprise Geocoding Module Universal Addressing Module United Arab Emirates AE ARE Address Now Module Universal Addressing Module United Kingdom GB GBR Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module United States US USA Address Now Module Enterprise Geocoding Module Enterprise Routing Module Universal Addressing Module United States Minor Outlying UM Islands UMI Address Now Module Universal Addressing Module Uruguay UY URY Address Now Module Enterprise Geocoding Module Universal Addressing Module Uzbekistan UZ UZB Address Now Module Universal Addressing Module Vanuatu VU VUT Address Now Module Universal Addressing Module Venezuela, Bolivarian Republic Of VE VEN Address Now Module Enterprise Geocoding Module Universal Addressing Module Viet Nam VN VNM Address Now Module Universal Addressing Module Virgin Islands, British VG VGB Address Now Module Universal Addressing Module Virgin Islands, U.S. VI VIR Address Now Module Universal Addressing Module Wallis and Futuna WF WLF Address Now Module Universal Addressing Module Administration Guide 123 Country ISO Codes and Module Support 124 ISO Country Name (English) ISO 3116-1 Alpha-2 ISO 3116-1 Alpha-3 Supported Modules Western Sahara EH ESH Address Now Module Universal Addressing Module Yemen YE YEM Address Now Module Universal Addressing Module Zambia ZM ZMB Address Now Module Enterprise Geocoding Module Universal Addressing Module Zimbabwe ZW ZWE Address Now Module Enterprise Geocoding Module Universal Addressing Module Spectrum™ Technology Platform 9.0 Notices © 2013 Pitney Bowes Software Inc. All rights reserved. MapInfo and Group 1 Software are trademarks of Pitney Bowes Software Inc. All other marks and trademarks are property of their respective holders. ® USPS Notices ® Pitney Bowes Inc. holds a non-exclusive license to publish and sell ZIP + 4 databases on optical and magnetic media. The following trademarks are owned by the United States Postal Service: CASS, CASS Link Link Certified, DPV, eLOT, FASTforward, First-Class Mail, Intelligent Mail, LACS , NCOA , PAVE, Link PLANET Code, Postal Service, POSTNET, Post Office, RDI, Suite , United States Postal Service, Standard Mail, United States Post Office, USPS, ZIP Code, and ZIP + 4. This list is not exhaustive of the trademarks belonging to the Postal Service. ® Link® Pitney Bowes Inc. is a non-exclusive licensee of USPS for NCOA processing. Prices for Pitney Bowes Software's products, options, and services are not established, controlled, or ™ approved by USPS® or United States Government. When utilizing RDI data to determine parcel-shipping ® costs, the business decision on which parcel delivery company to use is not made by the USPS or United States Government. Data Provider and Related Notices Data Products contained on this media and used within Pitney Bowes Software applications are protected by various trademarks and by one or more of the following copyrights: © Copyright United States Postal Service. All rights reserved. © 2013 TomTom. All rights reserved. TomTom and the TomTom logo are registered trademarks of TomTom N.V. © Copyright NAVTEQ. All rights reserved Data © 2013 NAVTEQ North America, LLC Fuente: INEGI (Instituto Nacional de Estadística y Geografía) Based upon electronic data © National Land Survey Sweden. © Copyright United States Census Bureau © Copyright Nova Marketing Group, Inc. Portions of this program are © Copyright- by Nova Marketing Group Inc. All Rights Reserved © Copyright Canada Post Corporation This CD-ROM contains data from a compilation in which Canada Post Corporation is the copyright owner. © 2007 Claritas, Inc. The Geocode Address World data set contains data licensed from the GeoNames Project (www.geonames.org) provided under the Creative Commons Attribution License ("Attribution License") located at http://creativecommons.org/licenses/by/3.0/legalcode. Your use of the GeoNames data (described in the Spectrum™ Technology Platform User Manual) is governed by the terms of the Attribution License, and any conflict between your agreement with Pitney Bowes Software, Inc. and the Attribution License will be resolved in favor of the Attribution License solely as it relates to your use of the GeoNames data. ICU Notices Copyright ©- International Business Machines Corporation and others. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above 126 Spectrum™ Technology Platform 9.0 Copyright copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. Administration Guide 127