Rtdm Guide.pdf 44k3g

>, where bankBalances is a double list type variable created from an upstream node named Process1. For more information, see “Creating Nodes” in SAS RealTime Decision Manager: ’s Guide.

Offers An offer is the enticement (a free gift, discount, and so on) that you present as a reply to the customer. The types of offer that you present are determined by the customer’s profile and actions. Offers can be delivered in real time synchronously to a channel or can be staged for future delivery by the configuration of the decision campaign. An offer can consist of multiple treatments, some of which might have been previously staged. Staged treatments ensure that the right offer is delivered in the right channel at the right time. Staged treatments might be used in the following circumstances: n An offer does not need to be made immediately after the segmentation and

eligibility rules are executed. n An offer might not be appropriate for the channel in which a campaign is

executed. n Delivery of the offer should be delayed to reduce the perception of spam.

To use staged treatments, staging must be configured on your system. For more information, see “Flows” on page 60.

14

Chapter 1 / Overview

15

2 Architecture Architecture of the SAS Intelligence Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Architecture of SAS Real-Time Decision Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Recommendations for Deg SAS Real-Time Decision Manager Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Overview of Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Overview of Deg SAS Real-Time Decision Manager Architecture . . . . . . . 19 SAS Deployment Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Platform Suite for SAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SAS Visual Analytics istration and Reporting . . . . . . . . . . . . . . . . . . . . . . . . . 20 Load Balancer for SAS Real-Time Decision Manager . . . . . . . . . . . . . . . . . . . . . . . 20 Storage Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Estimating Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Scalability and Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Server Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Best Practices for SAS Decision Services Performance and High Availability . . 24 SAS Real-Time Decision Manager Deployment Scenarios . . . . . . . . . . . . . . . . . . . 25 Tiers in the SAS Real-Time Decision Manager Architecture . . . . . . . . . . . . . . . . . . 29 SAS Metadata Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 SAS Client Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Data Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 SAS Server Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 SAS Visual Analytics Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 SAS Real-Time Decision Manager Server Design Middle Tier . . . . . . . . . . . . . . . . 41 Operational Middle Tier for SAS Real-Time Decision Manager Server or SAS Real-Time Decision Manager Run-Time Server . . . . 45 Reverse Proxy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 About the Object Spawner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 About the SAS Workspace Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 About the SAS Stored Process Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 About the SAS Pooled Workspace Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Operational, Development, and Test Environments . . . . . . . . . . . . . . . . . . . . . . . . . 49 About the Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Production Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Test and Production Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Choosing Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 A Typical Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

16 Chapter 2 / Architecture Life Cycle of a Decision Campaign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Development and Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Mark the Campaign for Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SAS Decision Services Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SAS Decision Services Repositories and Metadata Objects . . . . . . . . . . . . . . . . . . 54 Location of Files in the SAS Decision Services Repositories . . . . . . . . . . . . . . . . . 55 Create a SAS Decision Services Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Delete a SAS Decision Services Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Metadata Objects in the SAS Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Predefined Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Library Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

56 56 57 58 60 63 63 65 65

General I/O Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General I/O Write and SAS Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

65 65 66 70

Stored Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Dependent SAS Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAS Web Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAS Web Infrastructure Platform Data Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAS BI Web Services for SAS 9.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAS Federation Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DataFlux Secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAS Environment Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applications for Recording History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

71 71 71 71 72 72 72 72

Connection Points in the SAS Real-Time Decision Manager Architecture . . . . 73 Install Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Campaign Execution Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Database Connection Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 DS2 Execution Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 DS2 Publishing Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Self-Learner Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Integrating SAS Real-Time Decision Manager with Other SAS Products . . . . . 79 SAS Business Rules Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 SAS Model Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Architecture of the SAS Intelligence Platform 17

Architecture of the SAS Intelligence Platform The SAS Intelligence Platform is designed to efficiently access large amounts of data, while simultaneously providing timely information and insights to a large number of s. The platform uses an n-tier architecture that enables you to distribute functionality across computer resources, so that each type of work is performed by the resources that are most suitable for the job. A tier in the SAS architecture represents a conceptual category of software components that perform similar types of computing tasks and that require similar types of resources. Different tiers do not necessarily represent separate computers or groups of computers. More than one computer can be used for a specified tier as well. You can modify the SAS architecture to meet the demands of your workload. For a large company, the architecture can easily consist of many computers with different operating environments. For prototyping, demonstrations, or very small enterprises, the components for all of the tiers can be installed on a single computer. The architecture of the SAS Intelligence Platform consists of the following tiers. Clients

The client tier provides s with access to intelligence data and to functionality through web-based interfaces. For more information about the client tier for SAS Real-Time Decision Manager, see “SAS Client Tier” on page 31.

Middle tier

The middle tier enables s to access intelligence data and functionality via a web browser. This tier provides web-based interfaces for report creation and information distribution, while ing analysis and processing requests to the SAS servers. For more information about the middle tier for SAS Real-Time Decision Manager, see “SAS Real-Time Decision Manager Server Design Middle Tier” on page 41 and “Operational Middle Tier for SAS Real-Time Decision Manager Server or SAS Real-Time Decision Manager Run-Time Server” on page 45.

SAS servers

SAS servers perform SAS processing on your enterprise data. Several types of SAS servers are available to handle different workload types and processing intensities. The software distributes processing loads among server resources so that multiple client requests for information can be met without delay. For more information about the SAS server tier for SAS Real-Time Decision Manager, see “SAS Server Tier” on page 36.

Data sources

Data sources store your enterprise data. All of your existing data assets can be used, whether your data is stored in relational database management systems, SAS tables, or enterprise resource planning system (ERP) tables. For more information about the data tier for SAS Real-Time Decision Manager, see “Data Tier” on page 32.

18 Chapter 2 / Architecture For more information about the SAS Intelligence Platform, see SAS Intelligence Platform: Overview at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html.

Architecture of SAS Real-Time Decision Manager SAS Real-Time Decision Manager consists of two distinct phases of processing: the design phase and the operational environment. The architecture reflects these phases. Architecture for the design phase resembles a typical solution architecture. It contains a traditional set of servers (metadata, middle-tier, and compute). The servers are configured to manage the design process where a campaign is created with a decision flow to make a recommendation based on the customer’s eligibility to receive a particular offer. After the design phase is complete, the campaign is promoted to the operational environment. The operational environment is separated, or distinct, from the design environment. This does not have to be a physical or network separation, although in some cases it might be. Workload for the operational environment should be load balanced across two or more servers to accommodate high volumes of requests and provide acceptable response time and high availability. The SAS Decision Services Engine Server and SAS Federation Server are key components of the operational servers. For information about deploying SAS Real-Time Decision Manager Server (design environment) or SAS Real-Time Decision Manager Run-Time Server (operational environment), see SAS Customer Intelligence 6.5: Deployment Guide. A multi-tiered architecture is used to distribute functionality across computer resources.

Recommendations for Deg SAS RealTime Decision Manager Architecture Overview of Environments There are two types of environments that can be configured for SAS Real-Time Decision Manager: n SAS Real-Time Decision Manager Server n SAS Real-Time Decision Manager Run-Time Server

Note: By design, the planning application does not allow you to configure these together in the same plan. They must be separate because they each have their own SAS Metadata Server. Known as the design environment, SAS Real-Time Decision Manager Server includes design components such as SAS Customer Intelligence Studio and SAS Decision Services Design Server, and run-time components such as the

Recommendations for Deg SAS Real-Time Decision Manager Architecture

19

SAS Decision Services Engine Server. All of these components use a single set of SAS Application Servers and SAS Metadata Server in one environment. Known as the run-time or operational environment, SAS Real-Time Decision Manager Run-Time Server includes software required only for the SAS Decision Services Engine Server. The operational environment is separate from the design environment. The operational environment contains its own SAS Metadata Server and SAS Application Server and does not include any SAS Customer Intelligence components.

Overview of Deg SAS Real-Time Decision Manager Architecture SAS Real-Time Decision Manager can be configured in a variety of ways, depending on customer requirements and data volume. These components can be combined on the same physical server. In most cases, the components are spread across multiple servers for better load balancing, availability, or performance. When you design the architecture for SAS Real-Time Decision Manager at your site, there are several factors that you should consider. n SAS Web Application Server is the only ed web application server. n The non-distributed version of SAS Visual Analytics istration and

Reporting is included with SAS Real-Time Decision Manager. Allocate a separate machine for this component. If this SAS Visual Analytics middle tier and the SAS server tiers are placed on separate machines, the operating system (Windows or Linux) must be the same on both machines. n The SAS Real-Time Decision Manager Server (or design environment) and

the SAS Real-Time Decision Manager Run-Time Server (or operational environment) are deployed on separate metadata servers. A common and recommended topology for SAS Real-Time Decision Manager is to configure one SAS Real-Time Decision Manager Server or design environment and multiple SAS Real-Time Decision Manager Run-Time Server or operational environments. Using the plan file for the SAS Real-Time Decision Manager Run-Time Server, you can install and configure as many separate SAS Decision Services Engine or run-time environments as needed. This plan installs software needed only for the SAS Decision Services Engine environment, allowing for a small software footprint and improvement in overall performance. A SAS Federation Server instance is installed and configured on every machine that a SAS Decision Services Engine is deployed. n Consider creating one or more unique server contexts for SAS Customer

Intelligence. For more information, see SAS Intelligence Platform: System istration Guide at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html. n Select a database carefully. Your choice of databases might be limited,

based on the combination of SAS Customer Intelligence solutions at your site. The selection of a database should take into the possibility of adding a solution in the future to the currently licensed solutions.

20 Chapter 2 / Architecture

SAS Deployment Wizard You can use the SAS Deployment Wizard and the Middle Tier Node purpose for the planning application to add nodes for SAS Metadata Server and the Middle Tier. These nodes are automatically defined on the Define Machines page of the planning application file when the deployment plan is created. During configuration, the SAS Deployment Wizard typically deploys SAS Customer Intelligence web applications to individual managed SAS Web Application Server instances. A deployment that includes all of the SAS Customer Intelligence solutions with SAS Real-Time Decision Manager configures seven managed servers (SASServer1, SASServer2, SASServer6, SASServer7, SASServer11, SASServer12, and SASServer13). For more information about clustering your metadata server and middle-tier servers, see SAS Intelligence Platform: Installation and Configuration Guide.

Platform Suite for SAS SAS Customer Intelligence does not use any grid components from the Platform Suite for SAS. You use a scheduler to retrain self-learner processes. Standard operating system scheduling capabilities might not be flexible enough to meet more demanding tasks. In order to provide robust scheduling capability, you should add Platform Suite for SAS to your components.

SAS Visual Analytics istration and Reporting A non-distributed version of SAS Visual Analytics istration and Reporting is included with SAS Real-Time Decision Manager. This new addition is represented as an individual server, although it is possible to separate the middle tier from the SAS server tier. Install this component on a separate machine. You can license the distributed version of SAS Visual Analytics istration and Reporting or the full SAS Visual Analytics product to integrate with SAS Real-Time Decision Manager. The full product can be distributed or nondistributed. The distributed version runs only on Linux. The non-distributed versions run on Linux or Windows. A minimum of 16 cores is recommended for implementation of non-distributed versions. Implementation of distributed versions should include 4 servers and 64 cores. If you license the distributed version of SAS Visual Analytics istration and Reporting, install the component on a separate collection of machines. For information about how to delay SAS Visual Analytics istration and Reporting and how to place all of the SAS Visual Analytics istration and Reporting and LASR components on a separate machine in your plan, see the Help in the planning application.

Load Balancer for SAS Real-Time Decision Manager Production workloads for SAS Real-Time Decision Manager must be split across two or more operational servers that contain a SAS Decision Services Engine Server and SAS Federation Server. In order to balance incoming requests, a


21

load balancer might be necessary. If a load balancer is already installed at a site, configure this component to direct traffic to the operational servers.

Storage Architecture The storage for SAS Customer Intelligence components is organized into the following categories: n SAS installation files and binaries n SAS configuration files and configuration data n SASWORK n Customer data n Common data model

The first three areas are typical of any standard SAS deployment. Many SAS Customer Intelligence processes are driven by stored processes and large customer data sets. It is important to size the SAS workspace. Typically, customer data already exists. Storage parameters for those databases are defined. The common data model is stored in a relational database. Consider the space that must accommodate the expected volume of data such as history, response history, and presented treatment history tables. When you run some functions in SAS Real-Time Decision Manager, one or more single row transactions of the customer data might be initiated every time a campaign is executed. In these cases, make sure that the database is appropriately tuned and adequate for row-level transactions. The database must the latency requirements of the campaign.

Estimating Size When you plan SAS Real-Time Decision Manager configuration, consider the volume of transactions and complexity of decision flows that are processed by the SAS Decision Services Engine. You should also plan for the number of customer or model processes that are handled by SAS Federation Server.

High Availability SAS 9.4 improves the availability of the SAS platform. The areas of improved availability are SAS Metadata Server and middle-tier servers. These servers can be clustered with the SAS Deployment Wizard. The planning application automatically generates additional server node instances that can be used to create a cluster. For more information, see SAS Intelligence Platform: Web Application istration Guide at http://.sas.com/documentation/ onlinedoc/intellplatform/index.html. Not all web applications are candidates for clustering. The SAS Decision Services Monitor application is on the middle tier, but it is not capable of being clustered. SAS Federation Server, SAS Decision Services Engine, SAS Customer Intelligence Reporting, and related SAS servers can be replicated to distribute workload for SAS Real-Time Decision Manager while providing higher availability for those components. Each operational server should be configured with a co-located SAS Federation Server and SAS Decision Services Engine Server.


Scalability and Failover In SAS Decision Services, horizontal scalability and hardware failover are achieved through server clustering on multiple tiers. Vertical scalability and high performance are achieved by maximizing the parallel processing capabilities of the server hardware. The system is centrally managed using SAS Management Console. The SAS Decision Services engine is deployed to SAS Web Application Server. The clustering and load-balancing capabilities of the server combine with the SAS Decision Services threaded architecture to enable parallel execution. At any time, servers can be removed from or added to the cluster without stopping the application (for example, if a server fails and restarts). This operation is ed without human intervention: all configuration information that is required to initialize and operate the system is made available in a fail-safe manner within a cluster-wide lateral cache. This lateral cache is implemented using VMware vFabric GemFire, which does not require Datagram Protocol (UDP) multicast. In addition to the middle tier, SAS Decision Services includes a configurable cluster of SAS Federation Servers.


23

Figure 2.1 SAS Decision Services Run Time Call Center

Web

E-mail

Mobile

IVR

POS/ATM

SAS Decision Services Intranet, workflow, ESP

Node Engine Lateral Cache

SAS Federation Server

Node Load Balancer

DBMS (Cluster)

Engine Lateral Cache


Engine Server Cluster (sized as needed)

Open Metadata Repository SAS Management Console Plug-in

Server Hardware The choice of server hardware depends on the SAS Customer Intelligence solutions, volume of customer data and broadcasts, complexity of communications and campaigns, and expected response time. Larger volumes of data might require additional servers to ensure acceptable response time. A separate server is recommended for default SAS Visual Analytics istration and Reporting. If clustering of the middle tier servers or SAS Metadata Server is configured, each clustered node equates to a physical server. A customer who has licensed all of the SAS Customer Intelligence solutions might have ten or more servers in the production environment if clustering is configured. In many cases, development environments might fit on a single server.


Best Practices for SAS Decision Services Performance and High Availability n SAS Decision Services has a design environment and a run-time

environment. The design environment is used for developing, modifying, and functional testing of decision services. The run-time environment is used for production. A run-time environment can also be used for integration or performance testing. However, if a testing environment is deployed, it should be separate from the production environment. The production environment should always be dedicated to production processing only. High performance, measured in of throughput and latency, and around-theclock availability are typically critical for run-time environments and less important for design environments. n The following components are critical to run-time performance and

availability: o

engine

o


o

database management system

n In the run-time environment, the engine, SAS Federation Server, and

database instances should be installed on dedicated hardware. Service levels cannot be guaranteed if external software is allowed to consume resources. Batch processes and online transaction processing should never share hardware resources. n SAS Federation Server has approximately twice the throughput capability as

the engine. Therefore, an optimized deployment should assign more powerful hardware to the engines than to SAS Federation Server. n The numbers of servers that are allocated to the middle, SAS, and database

tiers should be proportional to your throughput and latency requirements. At least two servers in each tier are required to failover and ensure high availability. n The engine and SAS Federation Server tiers can either be co-located or

dislocated, as necessary. See your on-site SAS personnel for advice regarding which configuration is more appropriate for your specific deployment. Note: Co-located engine and SAS Federation Server tiers must be deployed on machines that use the same operating system. n SAS Metadata Server, SAS Management Console, and the object spawner

have a minimal impact on performance because they are not directly involved in transaction processing.


25

SAS Real-Time Decision Manager Deployment Scenarios Easy Button SAS Real-Time Decision Manager Server (Design Environment) Note: To use the “easy button” deployment, you must select only SAS RealTime Decision Manager Server (design environment) when you create your plan file. You cannot select both SAS Real-Time Decision Manager Server and SAS Real-Time Decision Manager Run-Time Server. An "easy button" deployment is a deployment where the default settings, where available, are used during the installation and configuration process. This results in a design-time system and a run-time system that is connected to a single metadata server. Easy button deployments are suitable for decision service design and functional testing, but are appropriate only for production use in cases where high performance and high availability are not required. The design-time system contains a design server for creating and modifying decision services. It contains many of the same software components as a production system, in order to enable functional testing of decision services. A major difference between a design environment and a production environment is that a production deployment typically includes load-balanced, clustered engine servers and multiple SAS Federation Server instances for scalability and high availability.

26 Chapter 2 / Architecture Figure 2.2 SAS Real-Time Decision Manager Server (Design Environment) C lient T ier SAS Management Console

Design Horizontal Cluster Tiers SAS Customer Intelligence Core (clustered)

S A S A pp lic ation S erv er Ti er

SAS Customer Intelligence Reporting (clustered)

SAS Metadata Server

SAS Customer Intelligence Studio (clustered)

Base SAS Object Spawner

SAS Decision Services Design Server (clustered)

SAS Stored Process Server SAS Workspace Server

E n gi n e Midd le T ier

SAS Pooled Workspace Server

SAS Decision Services Engine Server SAS Federation Server

W eb S erv er Ti er SAS Web Server

D es ig n Midd le Ti er

E n gi n e H o riz on tal C lu s ter Ti ers SAS Decision Services Engine Server (clustered) SAS Federation Server

ActiveMQ Broker SAS Customer Intelligence Core SAS Customer Intelligence Reporting SAS Customer Intelligence Studio SAS Decision Services Design Server SAS Federation Server SAS Federation Server Manager

SAS Real-Time Decision Manager Run-Time Server Deployments (Production Environment) SAS Real-Time Decision Manager Run-Time Server production deployments consist of the following major components: n SAS Decision Services Engine server cluster (at least two engine servers are

required for high availability) n one or more SAS Federation (TKTS) Servers and at least two co-located

SAS Federation Servers are required for high availability) n SAS Management Console plug-in, for centralized control and monitoring n SAS Web Server or a third-party load balancer n third-party database management system, clustered for high availability


27

n workspace server, for publishing activities and other DS2 assets to SAS

Federation Server n (Optional) SAS Stored Process Server for the execution of SAS BI Web

Services Figure 2.3 Production SAS Decision Services Engine Server

Middle Tier

Client Tier SAS Management Console

SAS Decision Services Engine Server Lateral Cache

Compute Tier Base SAS SAS Federation Server

Middle Tier SAS Decision Services Design Server SAS Customer Intelligence Core SAS Customer Intelligence Studio

SAS Tier Base SAS SAS Stored Process Server Object Spawner SAS Workspace Server

DBMS

SAS Pooled Workspace Server SAS Metadata Server Here are examples of the factors that affect hardware capacity planning: n peak transaction volume n maximum latency requirements n minimum throughput requirements n business logic complexity n analytic complexity n size of request and response messages n amount and frequency of disk I/O n whether you are deploying Real-Time Decision Manager treatment

campaigns, the number of treatments, treatment sets, custom -defined fields, and custom -defined field lists

28 Chapter 2 / Architecture n external system dependencies, such as external web service calls made by a

decision service

Scenario: Complex Business Logic and Light Analytics A typical SAS Real-Time Decision Manager Run-Time Server scenario might include business logic combined with one or two high-performance predictive models that generate scores, such as propensity or risk. For the purposes of this scenario, assume that all required data is ed in to the decision service through the event. Therefore, no database I/O occurs. In such a scenario, processing is approximately evenly divided between the business logic and the analytics. In general, the business logic executes in the engine middle tier and the analytics execute inside SAS Federation Server. Because a SAS Federation Server executes with approximately twice the throughput of the engine middle tier, a baseline topology might include a 16-core middle tier server and an 8-core SAS Federation Server. Alternatively, two engine servers could be allocated per SAS Federation Server, if all servers are equally powerful. The baseline topology hardware should be multiplied until latency and throughput requirements are achieved. A hardware failover capability requires at least two servers per tier. All SAS Federation Servers should have access to a common clustered database management system. This database should be clustered to failover. A common database should be used to allow all DS2 activity packages to be accessed by all SAS Federation Servers. Using servers of equal capacity for this scenario, a system capable of hardware failover would have four middle tier servers, two SAS Federation Servers, and a database server cluster. Although data I/O was not included in this scenario, a database management system might be used to store the activities, which are persisted in the database as DS2 packages. Alternatively, the DS2 packages can be stored in SAS data sets on a shared file system.

Scenario: Complex Business Logic and Complex Analytics Another typical SAS Decision Services scenario includes both complex business logic and complex analytics, where three or more predictive models, or one or more very complex models, are used. In this scenario, the analytics require more processing cycles than the business logic. Because a SAS Federation Server executes at approximately twice the speed of the engine middle tier and is doing twice as much work, a baseline topology might include a 16-core middle tier server and a 16-core SAS Federation Server. The baseline topology should be multiplied until latency and throughput requirements are achieved. A hardware failover capability requires at least two servers per tier. As mentioned earlier, all SAS Federation Servers should have access to a common clustered database management system. For this scenario, a typical system capable of hardware failover would have two middle tier servers, two SAS Federation Servers, a database server cluster, and SAS Web Server or a thirdparty front-end load balancer.

Tiers in the SAS Real-Time Decision Manager Architecture

29

Real-Time Decision Manager Server Treatment Set Campaign with 100 Treatment Campaigns Depending on a number of factors, such a deployment might require more than 100 cores in the production environment. This scenario should be planned with the assistance of SAS Professional Services. Treatment campaigns require special planning because they typically consume an order of magnitude more compute resources than advanced analytics, such as credit risk applications.

Heterogeneous Decision Service Considerations In reality, most deployments include a mix of variations on the scenarios described earlier. To determine the proportion of processing cycles that are consumed by business logic versus analytics, consider the cumulative effects of each decision service, as well as the relative frequencies of the events that are bound to each. When measuring your baseline system using historical data, record U use for each server at several points during the simulation run. The results will indicate whether the processing load is balanced, and where adjustments to hardware resources must be made. In addition to these examples, SAS Real-Time Decision Manager Server can generate complex decision flows that address specific business problems. To accurately plan hardware capacity, you must understand the processing that is performed by the flows that you will be running, the expected transaction volumes, data requirements, and performance constraints.

Database I/O Considerations Disk I/O is typically the most expensive operation that real-time systems perform. Therefore, database hardware capacity planning and performance tuning are critical to the performance of decision services that read from or write to disk. your database management system vendor for guidance.

Tiers in the SAS Real-Time Decision Manager Architecture SAS Metadata Tier The SAS metadata tier is where the central repository of metadata resides. The metadata tier is shared by all of the applications that run as part of SAS RealTime Decision Manager.

SAS Components in the Metadata Tier The following SAS components exist in the metadata tier and can exist in an optional metadata server node tier: SAS Foundation is the superset of all SAS software that is installable with the Base SAS installation. For a particular customer, SAS Foundation is a collection of software consisting of the of that superset that are required to the customer’s deployment.

30 Chapter 2 / Architecture SAS Metadata Server controls access to a central repository of metadata that is shared by all of the applications that run as part of SAS Real-Time Decision Manager.

Metadata in SAS Metadata Server Metadata for the following objects is generated and stored for SAS Real-Time Decision Manager: n tables for the common data model (extension tables, history tables,

response history tables, presented treatment history tables, and lookup tables). n authorization rules for objects (such as information maps, business contexts,

and campaigns) that are used by SAS Real-Time Decision Manager. Note: The authorization rules for the SAS Federation Server data sources are maintained using SAS Federation Server Manager. n IDs and s for SAS Real-Time Decision Manager that are used

to access a third-party server (for example, an Oracle database server). n stored processes. n DS2 code from DS2 packages. n SAS Customer Intelligence campaign objects and SAS Decision Services

campaign objects. For more information, see “Metadata Objects in the SAS Repositories” on page 56.

Files Used by SAS Metadata Server SAS Metadata Server uses the following files: Configuration sasv9_MetadataServer.cfg is located in \Lev1\SASMeta \MetadataServer and points to Sasv9.cfg in \Lev1\SASMeta. Sasv9.cfg points to the default SAS configuration file at C:\Program Files \SASHome\SASFoundation\9.4\sasv9.cfg. The metadata configuration file contains information about accessing a metadata server. The spawner uses the information that is contained in the configuration file to connect to a metadata server and to read the appropriate server definitions. To enable the spawner to connect to and read from the appropriate metadata from a metadata server, you must specify the appropriate information in the metadata configuration file. Log MetadataServer#d#b#y.log is located in \Lev1\SASMeta \MetadataServer\logs. This log file contains information ers who connect to SAS Metadata Server. For example, this log might show the status of SAS Metadata Server and might indicate whether a request from a client application was successful. The log entries also contain information that is useful for diagnosing server start-up problems, diagnosing authorization failures, and debugging method calls. According to the SAS Metadata Server options that you specify at invocation, SAS Metadata Server can write the following categories of information to the SAS log: n the start and stop information for SAS Metadata Server:

Tiers in the SAS Real-Time Decision Manager Architecture o

the ID

o

the SAS long version number

o

the SAS Metadata Model version

o

the directory where SAS Metadata Server was started

o

configuration file options

31

n connection and disconnection events n creation and deletion of a repository n opening, closing, pausing, resuming, and refreshing events n errors, such as these: o

task and thread exceptions

o

memory allocation errors

o

I/O errors

o

application logic errors

o

authentication errors

o

authorization failures

n authentication events n XML input strings and XML output strings n traces that are invoked by the debugging options in omaconfig.xml

For detailed documentation, see the SAS Metadata Server documentation, at http://.sas.com/documentation/onlinedoc/metadatasrvr/index.html.

SAS Client Tier The SAS client tier consists of Adobe Flash Player, web browsers such as Internet Explorer, Firefox, or Chrome, and the following SAS components: SAS Customer Intelligence Studio enables you to manage a campaign, definitions, and other items. SAS Information Map Studio provides a graphical interface that enables you to create and manage SAS Information Maps. Information maps provide a simplified layer between nontechnical business s and the complexities of databases and query languages. SAS Enterprise Guide is the primary reporting vehicle for SAS IT Resource Management. SAS Management Console is a Java application that provides a single point of control for istering your SAS servers and for managing metadata objects that are used throughout SAS Intelligence Platform. You can use SAS Management Console to connect to SAS Metadata Server and view and manage the metadata objects that are stored in the server's metadata repositories. Decision Services plug-in is specifically designed for s who want to update, control, or monitor a design-time, test, or production Decision Services environment. The plug-in can be accessed from a Windows client machine that runs SAS Management

32 Chapter 2 / Architecture Console. s of this plug-in are system s, system operators, or performance analysts. SAS Add-in for Microsoft Office is an add-in to Microsoft Office that enables the use of SAS data access, analysis, and reporting directly within Outlook, Excel, Word, and PowerPoint. SAS Enterprise Miner Note: SAS Enterprise Miner is included with your deployment only when you also license SAS Marketing Automation. is a data mining package designed to streamline the data mining process. SAS Enterprise Miner creates highly accurate predictive and descriptive models based on vast amounts of data that is gathered by an organization. SAS Enterprise Miner offers a set of integrated capabilities to create and share insights that are used to drive decisions faster and more accurately. SAS Model Manager Note: SAS Model Manager is included with SAS Real-Time Decision Manager only when you license SAS Enterprise Decision Manager or SAS Model Manager separately. is a web-based application that enables organizations to , modify, track, score, publish, and report on analytical models developed for SAS Enterprise Miner, SAS Enterprise BI software products, and operational applications. Organizations can organize modeling projects, develop and validate candidate models, assess candidate models for champion model selection, and publish and monitor champion models in a production environment. All model development and model maintenance personnel, including data modelers, validation testers, scoring officers, and analysts can use SAS Model Manager. SAS Business Rules Manager is a decision management application that enables you to create a database of business rules, connect those rules together into rules flows, and publish the rule flows for use by other applications. SAS Studio is a web application that provides a SAS development environment that is accessible from a web browser. This application provides access to libraries, data sets, and existing programs, while allowing the to develop new programs. Predefined tasks are available to generate code for the . Programming context assistance prompts s with syntax help while they are working in the Program Editor. SAS Private Java Runtime Environment (JRE) 7 SAS Foundation, the SAS middle tier, and certain SAS client applications require the use of a JRE. For all platforms other than z/OS, a private JRE is provided by SAS and installed by the SAS Deployment Wizard for the exclusive use of SAS products. SAS offers for this private JRE when used in conjunction with SAS software products under the same guidelines that govern for all other SAS products.

Data Tier Within the SAS data tier, campaign managers use SAS Information Map Studio to build information maps. The maps are used to identify which fields will be used in the prompts for the history-related tasks in SAS Customer Intelligence Studio. Information maps are also used by the self-learner process


33

to determine which subsets of customer are more likely to respond to which treatments. The list of data items that are available in the self-learner process comes from the information map.

Data Sources Customer data is typically stored in a ed relational database management system (RDMS). It is likely that this data already exists and is available before a deployment. The second key data source, the SAS Customer Intelligence common data model, is also stored in a relational database. This might be in the same database system or in a system provided by a separate provider. To prevent cross-database s and performance problems, store the common data model in the same database as the customer data. The common data model is created after the software deployment. Initially, it contains no data. If the data provider is a SQL Server database, the hardware must the Windows operating system.

Components Your data tier might include several sources of data for SAS Customer Intelligence processes. The sources of data are determined by the objectives of your organization and by company resources. You can access almost any type of data source by using SAS LIBNAME statements. Note: Some databases, such as PostgreSQL, perform a case-sensitive comparison of table or column names when the names are enclosed in quotation marks. For these databases, set the following options to No: n Preserve the column name as in the database management

system n Preserve the table name as in the database management system

SAS/ACCESS provides direct access to the following relational databases for SAS Real-Time Decision Manager: n Oracle n DB2 n Microsoft SQL Server on Windows through SAS/ACCESS for ODBC or

SAS/ACCESS for OLEDB n PostgreSQL n Teradata

Note: The Teradata database is not recommended because it is not designed to handle the high frequency of Write accesses required by SAS Real-Time Decision Manager. SAS/ACCESS provides access to the following data warehouse appliances: n Greenplum

Note: To avoid errors in processing Greenplum tables, set the following Greenplum server configuration value: SET standard_conforming_strings = 'ON'

n Netezza

34 Chapter 2 / Architecture For information about improving database performance, see “Improving Performance” on page 268. For the specific versions of each database that is ed, see your on-site SAS personnel. For information about SAS data sets and SAS/ACCESS, see SAS Intelligence Platform: Data istration Guide at http://.sas.com/documentation/onlinedoc/intellplatform/index.html.

Limit the Size of PostgreSQL Columns There is no limit on the length of columns in PostgreSQL tables that are created from SAS processes. If you want to limit the column length, use the following guidelines: n If the session encoding is UTF-8 and single- and multiple-byte characters are

used, specify DBCLIENT_MAX_BYTES=3. n If the session encoding is UTF-8 and only single-byte characters are used,

specify DBCLIENT_MAX_BYTES=1. n If the session encoding is LATIN1, specify DBCLIENT_MAX_BYTES=1 or do

not specify the setting. For more information, see SAS/ACCESS for Relational Databases at http:// .sas.com/documentation/onlinedoc/access/index.html.

ing Data for SAS Customer Intelligence The data sources that must be ed to the SAS Metadata Repository for access by SAS Customer Intelligence include the following tables: n any database source for SAS Customer Intelligence data (such as Oracle or

Teradata) that is referenced by a SAS Information Map. n the common data model tables. n (optional) libraries to contain lists and custom details. These libraries are

specified in the business context If a ID in Microsoft SQL Server is mapped to more than one database, specify the name of the initial database as the default database in the data source definition. To specify the name of the initial database: 1 In SAS Management Console, select the SQL server name from the Server

Manager plug-in. 2

Right-click the connection name and select Properties.

3 On the Options tab, specify the name of the data source.


35

Figure 2.4 Specify Data Source Name

4

In the ODBC Data Source , specify the name of the default database. Figure 2.5 Specify Default Database Name

SAS Library Resources SAS Customer Intelligence requires several SAS libraries that contain SAS metadata and operational data. Most of the required libraries are defined when the product is installed. The reporting libref library location is specified on the Settings tab of the business context. The metadata library is specified on the Metadata tab of the business context. that all SAS Customer Intelligence s, including saswb, have both Read and Write access to the physical location of the library.

36 Chapter 2 / Architecture You can specify the location of a libref in any preferred physical path. The physical path is represented in the following sections as . Note: Librefs in metadata are used for all libraries in a SAS Customer Intelligence Studio data process. These librefs are not used after a flow is deployed. For information ing general I/O resources to identify data, see “Flows” on page 60. Data process definitions require SAS libraries that are defined in Data Library Manager in SAS Management Console. This requirement makes it possible to select a table. The list of libraries is then filtered to show only those libraries in the corresponding SAS Decision Services Design repository folder for the current business context. For more information, see SAS Intelligence Platform: Data istration Guide at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html.

SAS Server Tier Note: The SAS Server Tier is included in the deployments for both SAS RealTime Decision Manager Server and the SAS Real-Time Decision Manager RunTime Server. Data is processed in the SAS Server Tier. The following SAS components are installed on the SAS Server Tier: SAS Foundation is the superset of all SAS software that is installable with the Base SAS installation. For a particular customer, SAS Foundation is a collection of software consisting of the of that superset that are required to the customer’s deployment. SAS Application Server Context is a metadata object that represents the SAS server tier in your environment. In the SAS Management Console interface, this type of object is called a SAS Application Server. It is a logical container for a set of application server components that execute code. By default, the application server object is named SASApp A SAS Application Server knows its server context (the context in which it is being used) and makes decisions based on that knowledge. SAS Object Spawner is a process that runs on the SAS server host and listens for requests, including requests from the SAS Customer Intelligence application server. When a request is received, the object spawner accepts the connection and sends a job to the workspace server or to the stored process server. For more information, see “About the Object Spawner” on page 47. SAS Workspace Server provides access to SAS software features such as the SAS language, SAS libraries, the server file system, results content, and formatting services. A SAS Workspace Server surfaces the SAS programming environment to calling clients through an application programming interface (API). SAS Workspace Server is provided with SAS Integration Technologies and is accessed through the IOM workspace interface. This interface provides access to SAS Foundation software features such as the SAS language, SAS libraries, the server file system, results content, and formatting services. A SAS workspace represents a session with the SAS System, and it is functionally equivalent to a SAS Display Manager session or the execution of


37

the SAS System as a batch job. For more information, see “About the SAS Workspace Server” on page 47. SAS Pooled Workspace Server uses server-side pooling and provides access to SAS features such as the SAS programming language and libraries. Server-side pooling means that the spawner directs clients to a server that they are allowed to use as specified in the metadata. SAS Stored Process Server provides storage, access locations, and execution for stored processes. SAS Stored Process Servers are part of SAS Integration Technologies. A stored process is a SAS program that is stored on a server and can be executed as required by requesting applications. You can use stored processes for web reporting, analytics, building web applications, delivering packages to clients or to the middle tier, and publishing results to channels or repositories. Stored processes can also access any SAS data source or external file and create new data sets, files, or other data targets ed by SAS. You must use SAS Metadata Server to ister SAS Stored Processes. To make a stored process accessible to client applications, you must allocate a storage location that your server can access. Then, use SAS Business Intelligence Manager to create metadata that describes the stored process and its location. SAS Business Intelligence Manager stores this metadata on SAS Metadata Server so that it can be accessed by client applications. For more information, see “About the SAS Stored Process Server” on page 48. SAS/CONNECT Server provides computing resources on remote machines where SAS Integration Technologies is not installed. SAS/CONNECT links a SAS client session to a SAS server session. The SAS/CONNECT client session is the initial SAS session that creates and manages one or more server sessions. The SAS/CONNECT server sessions can run on the same computer as the client (for example, an SMP computer) or on a remote computer across a network. SAS/ACCESS is a solution for integrating SAS and third-party databases. You can read, write, and update data regardless of the database or platform. This solution enables organizations to bring different source system data together into a cohesive and unified environment. SAS Web Infrastructure Platform Data Server is the default location for middle-tier data such as alerts, comments, and workflows, as well as data for SAS Content Server. The server, which is stored in PostgreSQL, is provided as an alternative to using a third-party DBMS. (The server cannot be used as a general-purpose data store.) The SAS Web Infrastructure Platform is a collection of services and applications that provide common infrastructure and integration features to be used by SAS web applications. SAS Web Infrastructure Platform Scheduling Services is a collection of middle-tier services and applications that provide infrastructure and integration features that are shared by SAS web applications and other HTTP clients. SAS Environment Manager Agent is a web-based component in Base SAS software that enables you to visualize, monitor, and manage your SAS deployment using advanced monitoring and management capabilities. SAS Environment Manager

38 Chapter 2 / Architecture collects alerts, notifications, and data from your servers and presents that information in a dashboard. SAS Federation Server is a data server that executes SAS Decision Services activities that are written in the DS2 programming language. For more information, see SAS Federation Server ’s Guide. SAS Federation Server Manager is used to configure and manage the SAS Federation Server DSNs and data services.

SAS Visual Analytics Tier Note: The SAS Visual Analytics Tier is included only in a SAS Real-Time Decision Manager Server deployment. SAS Visual Analytics and SAS LASR Analytic Server are not included in a SAS Real-Time Decision Manager RunTime Server deployment. The SAS Visual Analytics istration and Reporting Server and SAS Visual Analytics istration and Reporting Middle Tier are installed on the SAS Visual Analytics Tier. These components are included in many SAS 9.4 solutions and technology packages to provide enhanced reporting and printing capabilities The following SAS software components are installed on the SAS Visual Analytics istration and Reporting Server: SAS LASR Analytic Server is an analytic platform that provides a secure, multi- environment for concurrent access to data that is loaded into memory. The server can take advantage of a distributed computing environment by distributing data and the workload among multiple machines and performing massively parallel processing. The server can also be deployed on a single machine where the workload and data volumes do not demand a distributed computing environment. SAS Application Server Context is a metadata object that represents the SAS server tier in your environment. In the SAS Management Console interface, this type of object is called a SAS Application Server. It is a logical container for a set of application server components that execute code. By default, the application server object is named SASApp. A SAS Application Server knows its server context (the context in which it is being used) and makes decisions based on that knowledge. SAS Foundation is the superset of all SAS software that is installable with the Base SAS installation. For a particular customer, SAS Foundation is a collection of software consisting of the of that superset that are required to the customer’s deployment. SAS Object Spawner is an application that initiates the workspace servers and stored process servers. An object spawner runs on each machine where you want to run a workspace server or stored process server, listens for requests, and launches the servers as necessary. For more information, see “About the Object Spawner” on page 47.


39

SAS Pooled Workspace Server uses server-side pooling and provides access to SAS features such as the SAS programming language and libraries. Server-side pooling means that the spawner directs clients to a server that they are allowed to use as specified in the metadata. SAS Stored Process Server provides storage, access locations, and execution for stored processes. SAS Stored Process Servers are part of SAS Integration Technologies. A stored process is a SAS program that is stored on a server and can be executed as required by requesting applications. You can use stored processes for web reporting, analytics, building web applications, delivering packages to clients or to the middle tier, and publishing results to channels or repositories. Stored processes can also access any SAS data source or external file and create new data sets, files, or other data targets ed by SAS. You must use SAS Metadata Server to ister SAS Stored Processes. To make a stored process accessible to client applications, you must allocate a storage location that your server can access. Then, use SAS Business Intelligence Manager to create metadata that describes the stored process and its location. SAS Business Intelligence Manager stores this metadata on SAS Metadata Server so that it can be accessed by client applications. For more information, see “About the SAS Stored Process Server” on page 48. SAS Workspace Server provides access to SAS software features such as the SAS language, SAS libraries, the server file system, results content, and formatting services. A SAS Workspace Server surfaces the SAS programming environment to calling clients through an application programming interface (API). SAS Workspace Server is provided with SAS Integration Technologies and is accessed through the IOM workspace interface. This interface provides access to SAS Foundation software features such as the SAS language, SAS libraries, the server file system, results content, and formatting services. A SAS workspace represents a session with the SAS System, and is functionally equivalent to a SAS Display Manager session or the execution of the SAS System as a batch job. For more information, see “About the SAS Workspace Server” on page 47. SAS/ACCESS is a solution for integrating SAS and third-party databases. You can read, write, and update data regardless of the database or platform. Enables organizations to bring different source system data together into a cohesive and unified environment. SAS/CONNECT Server provides computing resources on remote machines where SAS Integration Technologies is not installed. SAS/CONNECT links a SAS client session to a SAS server session. The SAS/CONNECT client session is the initial SAS session that creates and manages one or more server sessions. The SAS/CONNECT server sessions can run on the same computer as the client (for example, an SMP computer) or on a remote computer across a network. SAS Environment Manager Agent is a web-based component in Base SAS software that enables you to visualize, monitor, and manage your SAS deployment using advanced monitoring and management capabilities. SAS Environment Manager collects alerts, notifications, and data from your servers and presents that information in a dashboard.

40 Chapter 2 / Architecture SAS Solutions LASR Analytic Server When SAS Real-Time Decision Manager is deployed, the SAS Customer Intelligence LASR Analytic Server, SAS Visual Analytics Middle Tier, and its associated libraries are created on the SAS Visual Analytics Tier. For more information, see Chapter 6, “Displaying Reports in the Reports Workspace,” on page 195. The following SAS software components are installed on the SAS Visual Analytics Middle Tier: SAS Visual Analytics enables you to view SAS LASR Analytic Server and manage server connections by starting or stopping them in the LASR Tables tab. You can load tables from SAS metadata to the SAS LASR Analytic Servers, HDFS, or to co-located providers such as Teradata and Greenplum servers, and them as LASR tables. Tables that are loaded to the SAS LASR Analytic Server are referred to as LASR tables. Tables that are loaded can be unloaded and reloaded as needed. SAS Visual Analytics Hub is the main entry point for any web-based client from SAS. Each application uses the banner component to implement a common way to navigate between the SAS Visual Analytics Hub and the applications that integrate with it. SAS Visual Data Builder enables analysts and data s to perform analytic data preparation. You can build queries to perform s, add calculated columns, and subset and sort data. Several productivity features speed the creation of columns based on common aggregation functions. After you design your queries, you can reuse them as subqueries for more sophisticated queries, export them as jobs for scheduling, or schedule the query directly from the interface. SAS Visual Data Builder also provides a series of features that are used in deployments that include SAS LASR Analytic Server. You can load an existing table directly into memory, load the results of a query into memory, or append rows to an in-memory table on a server. Search Interface to SAS Content is a web-based application that enables you to search SAS Business Analytics platform content though various search engines and browser tools. It enables searching SAS content (such as reports, information maps) in SAS Metadata Server. SAS Visual Analytics Designer enables you to create reports or dashboards that can be saved and viewed on either a mobile device or in the SAS Visual Analytics Viewer. SAS Visual Analytics Designer is part of the SAS Visual Analytics product that enables a with either the Analysis or istration role to view, interact with, and create reports. Report authors can easily create reports and dashboards based on data sources that have been provided by an . They can also update reports that were created from visual explorations. Report authors can also create reports by importing objects or visual explorations from other reports. They can also define interactions (either filtering or brushing) for report objects and include SAS analytical results into a single report.


41

SAS Visual Analytics Services provides internal services that the suite of SAS Visual Analytics products. SAS Visual Analytics Report Viewer is a feature in SAS Visual Analytics that enables s with a Report Viewing role to view and add comments to SAS Visual Analytics report content. SAS Visual Analytics Graph Builder is a feature in SAS Visual Analytics that enables you to create graph objects, which then become available in the SAS Visual Analytics Designer for use in reports. You do not associate real data with the graph objects in the graph builder. Rather, you build graph objects or templates using sample data that is shipped with the graph builder. Report designers assign data when they include your graph objects in their reports. The graph objects that you build have a consistent appearance that is compatible with the designer’s graph objects. The graph builder enables you to produce a wide array of graph objects with more options for layouts and visual properties. Using the graph objects that you build, report designers can create simple or complex graphical views of their data.

SAS Real-Time Decision Manager Server Design Middle Tier Note: SAS Real-Time Decision Manager Server Design Middle Tier is included only with a SAS Real-Time Decision Manager Server deployment. It is not included with the SAS Real-Time Decision Manager Run-Time Server deployment. However, the SAS Real-Time Decision Manager Run-Time Server deployment includes the SAS Business Intelligence and the web application components from this tier. The deployment does not include any SAS Customer Intelligence or SAS Business Rules components from this tier. The design-time system contains a design server for creating and modifying decision services. It contains many of the same software components as a production system, in order to enable functional testing of decision services. A major difference between a design environment and a production environment is that a production deployment typically includes load-balanced, clustered engine servers and multiple SAS Federation Server instances for scalability and high availability. The SAS Web Application Server that is installed on the design middle tier contains the following applications: SAS Customer Intelligence Core a middle-tier application that enables you to rapidly create, modify, and manage marketing campaigns ranging from simple to sophisticated, multichannel campaigns. SAS Model Manager Note: SAS Model Manager is included with SAS Real-Time Decision Manager only when you license SAS Enterprise Decision Manager or SAS Model Manager separately. a web-based application that enables organizations to , modify, track, score, publish, and report on analytical models developed for SAS Enterprise Miner, SAS Enterprise Business Intelligence software products, and operational applications. Organizations can organize modeling projects, develop and validate candidate models, assess candidate models for

42 Chapter 2 / Architecture champion model selection, and publish and monitor champion models in a production environment. All model development and model maintenance personnel, including data modelers, validation testers, scoring officers, and analysts can use SAS Model Manager. SAS Business Rules Manager a decision management application that enables you to create a database of business rules, connect those rules together into rules flows, and publish the rule flows for use by other applications. SAS Business Rules Manager provides the following capabilities: n data management n vocabulary management n business rule authoring n rule set management n rule flow authoring and publishing

SAS Decision Services Design Server enables you to create, test, edit, and delete decision flows through a web service API. SAS Customer Intelligence Reporting enables cross-component reporting and consolidated handling of response and history. The SAS Customer Intelligence Reporting data model includes SAS Marketing Automation, SAS Interaction Management, SAS Real-Time Decision Manager, SAS Marketing Optimization, SAS Web Analytics, SAS Digital Marketing, and SAS OnDemand Veridiem MRM. SAS Customer Intelligence Studio enables you to manage a campaign, definitions, and other items. SAS Web Report Studio enables you to view, edit, and save published campaign data in a customized report or in a treatment performance report. Note: SAS Customer Intelligence Studio includes sample reports for SAS Web Report Studio. SAS Web Infrastructure Platform collection of services and applications that provide common infrastructure and integration features to be used by SAS web applications. These services and applications provide the following benefits: n consistency in installation, configuration, and istration tasks for web

applications n greater consistency in s' interactions with web applications n integration among web applications as a result of the ability to share

common resources SAS Content Server stores digital content (such as documents, reports, and images) that is created and used by SAS web applications. The SAS Content Server contains SAS Customer Intelligence objects such as campaigns and definitions. The SAS Content Server also stores documents and other files that are to be displayed in the SAS Information Delivery Portal or in SAS solutions. The SAS Content Server is part of the SAS Web Infrastructure Platform.


43

SAS Enterprise Miner Note: SAS Enterprise Miner is deployed with SAS Real-Time Decision Manager only when you license SAS Marketing Automation, SAS Enterprise Decision Manager, or SAS Enterprise Miner. is a data mining package that is designed to streamline the data mining process. SAS Enterprise Miner creates highly accurate predictive and descriptive models based on vast amounts of data that is gathered by an organization. SAS Enterprise Miner offers a set of integrated capabilities to create and share insights that are used to drive decisions faster and more accurately. SAS Flex Application Themes is an interface that is provided by SAS Flex Application Themes displays some SAS web applications with a Flex interface. SAS Studio is a web application that provides a SAS development environment that is accessible from a web browser. This application provides access to libraries, data sets, and existing programs, and also allows the to develop new programs. Predefined tasks are available to generate code for the . Programming context assistance prompts s with syntax help while they are working in the Program Editor. SAS Deployment Backup and Recovery provides an integrated method for backing up and recovering your SAS content across multiple tiers and machines. The tool is installed on the middle tier as part of the SAS Web Infrastructure Platform. It connects with the SAS Deployment Agent on each middle-tier and server-tier host machine and backs up the following components: n the metadata server, including all ed metadata repositories, the

repository manager, and the server’s configuration directory. n the contents of the Data directories, SASEnvironment directories, and

server configuration directories for each server on the SAS server tier. (If symbolic links in these directories point to other locations, the referenced locations are not backed up.) n the SAS Content Server repository. n the databases that are managed by the SAS Web Infrastructure Platform

Data Server. By default, all of the databases are backed up. You can modify the backup configuration so that only selected databases are backed up. n additional directories under SAS-configuration-directory/Levn, as

specified by the . By default, the SAS Deployment Backup and Recovery tool backs up these items automatically each Sunday at 1:00 a.m. Backup files are retained for a period of 30 days. Batch commands are available on each host machine to use in istering backups and recoveries. The following SAS software components are also installed on the SAS RealTime Decision Manager Server Design Middle Tier: SAS Web Server is an HTTP server. The server is based on Pivotal Web Server. SAS configures the server with the following features:

44 Chapter 2 / Architecture n automatically configured as a load-balancing HTTP server when SAS

Web Application Server is clustered. n automatically updated to route web sessions (round robin) to SAS Web

Application Server instances when clustered. n can be configured for HTTPS automatically. You must supply a signed

certificate and a private key. You can follow manual steps to change a configuration that used HTTP to HTTPS. n automatically configured to cache static web content like JavaScript files,

cascading style sheets, and graphics files. The following advanced configurations are possible, but require manual configuration that is not automatically updated: n adding instances of SAS Web Server to form a cluster n interacting with customer-supplied load-balancing hardware or software

SAS Environment Manager Server is responsible for communicating with the agents. It collects information about items such as discovered resources, metrics, and availability, and issues control actions received from the SAS Environment Manager application. Collected data is stored in the SAS Environment Manager database. SAS Environment Manager Middle Tier monitors, tracks, and manages SAS resources, including SAS Foundation servers and the SAS Web Application Server. SAS Environment Manager can be used to build dashboards that present performance, resource consumption, and availability data from a variety of services. It also provides the capability to monitor logs and trigger alerts based on pre-defined conditions. To be effectively used, this tool must have an agent deployed on each tier. SAS Environment Manager Agent is a web-based component in Base SAS software that enables you to visualize, monitor, and manage your SAS deployment using advanced monitoring and management capabilities. SAS Environment Manager collects alerts, notifications, and data from your servers and presents that information in a dashboard. SAS Cache Server is a distributed data management platform providing dynamic scalability, high performance, and database-like persistence. It blends advanced techniques like replication, partitioning, data-aware routing, and continuous querying. The SAS Cache Locator is a process that tells new connecting where running are located and also provides load balancing for server use. SAS Federation Server Manager is used to configure and manage the SAS Federation Server DSNs and data services. SAS Foundation Services is a set of infrastructure and extension services that the development of integrated, scalable, and secure applications based on Java. The design model of SAS Foundation Services s both local and remote resource deployment and promotes resource sharing among applications. Sharing can occur for a specific session, for a specific , or globally, as appropriate. At


45

the same time, the model controls access to protected resources based on privileged- status and group hip. Note: SAS Environment Manager Agent and clustered SAS web applications in the SAS Web Application Server can be installed on an optional middle-tier node.

Operational Middle Tier for SAS Real-Time Decision Manager Server or SAS Real-Time Decision Manager Run-Time Server Note: The Operational Middle Tier is included in the deployments for SAS RealTime Decision Manager Server and SAS Real-Time Decision Manager RunTime Server. The Operational Middle Tier is a production environment that typically includes load-balanced, clustered engine servers and multiple SAS Federation Server instances for scalability and high availability. The SAS Web Application Server that is on installed on the Operational Middle Tier includes the following components: SAS Decision Services Engine Server executes the decision flows that provide the real-time analytical decisions. SAS Decision Services Engine Servers are configured in an application server cluster. SAS Customer Intelligence Reporting enables cross-component reporting and consolidated handling of response and history. The SAS Customer Intelligence Reporting data model includes SAS Marketing Automation, SAS Interaction Management, SAS Real-Time Decision Manager, SAS Marketing Optimization, SAS Web Analytics, SAS Digital Marketing, and SAS OnDemand Veridiem MRM. The following SAS software components are also installed on the Operational Middle Tier: SAS Foundation is the superset of all SAS software that is installable with the Base SAS installation. For a particular customer, the SAS Foundation is a collection of software consisting of the of that superset that are required to the deployment of SAS Customer Intelligence Studio. SAS Federation Server 1 and SAS Federation Server 2 are data servers that execute SAS Decision Services activities that are written in the DS2 programming language. For more information, see SAS Federation Server ’s Guide. SAS Federation Server Manager is used to configure and manage the SAS Federation Server DSNs and data services. SAS Application Server Context is a metadata object that represents the SAS server tier in your environment. In the SAS Management Console interface, this type of object is called a SAS Application Server. It is a logical container for a set of application server components that execute code. By default, the application server object is named SASApp. Note: In SAS deployments prior to SAS 9.2, the default SAS Application Server is named SASMain.

46 Chapter 2 / Architecture A SAS Application Server knows its server context (the context in which it is being used) and makes decisions based on that knowledge. SAS Object Spawner is an application that initiates the workspace servers and stored process servers. An object spawner runs on each machine where you want to run a workspace server or stored process server, listens for requests, and launches the servers as necessary. For more information, see “About the Object Spawner” on page 47. SAS Pooled Workspace Server uses server-side pooling and provides access to SAS features such as the SAS programming language and libraries. Server-side pooling means that the spawner directs clients to a server that they are allowed to use as specified in the metadata. SAS Stored Process Server provides storage, access locations, and execution for stored processes. SAS Stored Process Servers are part of SAS Integration Technologies. A stored process is a SAS program that is stored on a server and can be executed as required by requesting applications. You can use stored processes for web reporting, analytics, building web applications, delivering packages to clients or to the middle tier, and publishing results to channels or repositories. Stored processes can also access any SAS data source or external file and create new data sets, files, or other data targets ed by SAS. For more information, see “About the SAS Stored Process Server” on page 48. You must use SAS Metadata Server to ister SAS Stored Processes. To make a stored process accessible to client applications, you must allocate a storage location that your server can access. Then, use SAS Business Intelligence Manager to create metadata that describes the stored process and its location. SAS Business Intelligence Manager stores this metadata on SAS Metadata Server so that it can be accessed by client applications. SAS Environment Manager Agent is a web-based component in Base SAS software that enables you to visualize, monitor, and manage your SAS deployment using advanced monitoring and management capabilities. SAS Environment Manager collects alerts, notifications, and data from your servers and presents that information in a dashboard.

Reverse Proxy Server Note: A reverse proxy server is included in the SAS Real-Time Decision Manager Server deployment and in the SAS Real-Time Decision Manager RunTime Server deployment. A standard SAS Customer Intelligence deployment now also includes the SAS Web Server. The SAS Web Server is an HTTP, HTTPS reverse proxy server that is configured as a single connection point for SAS web applications. If you cluster the SAS Web Application Server, the SAS Web Server is configured automatically to perform load balancing. Secure Sockets Layer (SSL) can be enabled during configuration with the SAS Deployment Wizard to provide secure communication. This server can be deployed in the DMZ portion of the network or in the domain with the remaining SAS server tier and middle-tier servers. The SAS


47

Deployment Wizard can automatically configure the SAS Web Server to provide secure communications (HTTPS). The SAS Web Server serves as the proxy, or entry point, to the SAS Web Application Servers. The Web Infrastructure Platform and related services, SAS Deployment Backup, SAS Studio and standard EBI applications reside in SASServer1 and SASServer2. The JVM for SASServer7 houses the SAS RealTime Decision Manager applications. Applications for SAS Visual Analytics istration and Reporting are located in SASServer12_1, and SAS Federation Server Manager is located in SASServer13_1. If you also licensed SAS Enterprise Decision Manager, SAS Marketing Automation, or SAS Enterprise Miner, SAS Enterprise Miner is deployed to SASServer11_1.

About the Object Spawner The object spawner requires the following software to be installed on the computer that is assigned to the SAS server tier: n SAS 9 software or later n SAS Integration Technologies n SAS Metadata Server

Note: SAS/SECURE is an optional component. The object spawner uses the following files: Executable ObjectSpawner.bat (Windows) or ObjectSpawner.sh (UNIX) is typically located in Lev1\ObjectSpawner on the SAS server computer. Configuration metaConfig.xml is located in \Lev1\ObjectSpawner. The configuration file contains the name of the metadata server and the credentials for the SAS Trusted . Log Objspawn.log is located in \ObjectSpawner\Logs. You can view the object spawner log file in order to troubleshoot connections between the client and server computers. The object spawner log file is not created by default. To create the object spawner log file, see SAS Intelligence Platform: System istration Guide at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html. The object spawner must be refreshed to include any changes that are made to autoexec_mods.sas and sasv9.cfg. For more information, see SAS Intelligence Platform: Application Server istration Guide at http:// .sas.com/documentation/onlinedoc/intellplatform/index.html.

About the SAS Workspace Server The SAS Workspace Server enables client applications to submit SAS code to a SAS session that uses an application programming interface (API). Your environment can include one or more workspace servers. When IT professionals process a campaign , SAS code is generated by the computation engine on the middle tier, and the code is submitted to a workspace server. SAS Workspace Server uses the following files:

48 Chapter 2 / Architecture Executable You can find the name and location of your workspace servers by using the SAS Server Manager in SAS Management Console. Log Workspace servers are not initially configured to produce log files. For troubleshooting purposes, workspace server logs can be helpful because they capture calls that are made to the database. In these situations, you can use the alternative logging configuration file (logconfig.trace.xml) that is provided in each workspace server’s configuration directory. For information about managing logs for the workspace server, see SAS Intelligence Platform: System istration Guide at http://.sas.com/ documentation/onlinedoc/intellplatform/index.html.

About the SAS Stored Process Server The SAS Stored Process Server executes and delivers results from SAS Stored Processes in a multi-client environment. SAS Stored Processes are SAS programs that are stored centrally and that can be executed by business s and by client programs on demand. The SAS Stored Process Server uses stored processes to insert the dynamic values into the various treatment tables when you use web services for history tables. The SAS Stored Process Server performs work that is similar to the workspace server. For information about the difference between the two servers, see SAS Intelligence Platform: Application Server istration Guide at http:// .sas.com/documentation/onlinedoc/intellplatform/index.html. Stored processes are used in SAS Customer Intelligence to perform computations. For information about stored process software requirements, see SAS Stored Processes: Developer’s Guide at http://.sas.com/documentation/ onlinedoc/inttech/index.html. The SAS Stored Process Server uses the following files: Executable In SAS Management Console, the initial stored process server is configured as a load-balancing server named SASApp-Stored Process Server. Find the name and location of the SAS Stored Process Server by using the Server Manager in SAS Management Console. Configuration sasv9.cfg is located in \Lev1\SASApp\StoredProcessServer and calls sasv9.cfg that is located in SASApp. Log The stored process server log is located in \Lev1\SASApp \StoredProcessServer\logs. The log file for the stored process server is useful for troubleshooting the execution of Split nodes, Limit nodes, and exports. Log parameters are specified in sasv9_StorProcSrv.cfg. For information about managing logs, see SAS Intelligence Platform: System istration Guide at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html.

Operational, Development, and Test Environments

49

Each stored process server process handles multiple s, and by default each server uses multiple server processes. A load-balancing algorithm distributes client requests between the server processes. By default, the object spawner starts the processes of the stored process server by authenticating the SAS Spawned Servers ID, sassrv. For information about load balancing, see SAS Intelligence Platform: Application Server istration Guide at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html.

About the SAS Pooled Workspace Server The SAS Pooled Workspace Server is used to publish tables to the common data model and to deploy DS2 code to the SAS Federation Server. A stored process must be run on a SAS Pooled Workspace Server in order for the SAS Decision Services Engine to publish the DS2 code to the SAS Federation Server. Therefore, the SAS Decision Services Engine Server communicates relevant information about the custom DS2 code to the SAS Pooled Workspace Server, which then sends a request to SAS Federation Server to publish the custom DS2 code. If the SAS Pooled Workspace Server is not also co-located with the SAS Federation Server, then the stored process cannot find a SAS Federation Server instance at localhost. To address this issue, install the SAS Pooled Workspace Server on the same computer where an instance of SAS Federation Server is installed. For more information, see “Custom DS2 Code Processes” on page 315.

Operational, Development, and Test Environments About the Environments When you license SAS Real-Time Decision Manager, you receive licenses for SAS Real-Time Decision Manager Server (also known as the design environment) and SAS Real-Time Decision Manager Run-Time Server (also known as the operational environment). The license that you select in the Planning Application determines which environment is deployed. If you select SAS Real-Time Decision Manager Server for your system, then the design environment is deployed. This environment includes the SAS Customer Intelligence component (SAS Real-Time Decision Manager), SAS Decision Services Design Server, SAS Decision Services Engine Server, SAS Federation Server, SAS Visual Analytics and Reporting, SAS LASR Analytic Server, SAS Metadata Server, and SAS Platform Business Intelligence components. If you select SAS Real-Time Decision Manager Run-Time Server for your system, then the deployed operational environment contains only SAS Decision Services Design Server (not used), SAS Decision Services Engine Server, SAS Federation Server, SAS Metadata Server, and some SAS Business Intelligence components. The development environment enables business s to create, test, edit, and delete campaigns. The SAS Decision Services Design Server provides this functionality through a web service API. SAS Real-Time Decision Manager uses

50 Chapter 2 / Architecture the SAS Decision Services Design Server on SASServer7 to execute this functionality on the s' behalf. From a software topology perspective, the test and operational environments are identical. The operational environment provides the capabilities and performance required for continual operation, twenty-four hours a day, every day of the year. As with the development environment, decision flows and their building blocks are stored in a repository. Repositories and their contents are managed by the Decision Services Manager plug-in or client application plug-ins. An important function of the Decision Services Manager plug-in (within the test and production environments) is to activate or deactivate decision flows. Activating or deactivating decision flows either connects or disconnects decision flows with operational channels or systems.

Production Environment The production environment consists of either a single instance or multiple instances of the following servers, depending on performance and availability requirements. n SAS Metadata Servers contain artifacts such as global variables, SAS

activities, events, and flows. n SAS Decision Services Engine Servers are configured in an application

server cluster. These servers execute the decision flows that provide the real-time analytical decisions. n SAS Federation Servers primarily run the SAS activities and score code that

are based on DS2. n SAS Web Servers are HTTP servers that are used to provide load-balancing

solutions for the real-time decision cluster enterprise. Using Service-Oriented Architecture (SOA) integration through web services, SAS Web Server is used as an integration point between external applications and a SAS Decision Services cluster. For more information, see the SAS Intelligence Platform Middle-Tier ’s Guide. n SAS Web Application Server can be configured as a cluster and used for

deployment of the SAS Decision Services Engine Server. n Database Servers store data and DS2 packages that implement SAS activity

methods. SAS servers can be used to run BI web services for applications that require the execution of procedures or macro code. The SAS Decision Services cluster enterprise uses open standards extensively in order to simplify integration and maximize interoperability.

Development Environment The development environment enables business s to create, test, edit, and delete campaigns. The SAS Decision Services Design Server provides this functionality through a web service API. SAS Real-Time Decision Manager uses the SAS Decision Services Design Server on SASServer7 to execute the above functionality on the s' behalf. Decision flows and their building blocks (events, activities, global variables, and system resources) are stored in a repository folder. Each repository folder

Operational, Development, and Test Environments

51

resides in SAS Metadata Server. Repositories are managed by the Decision Services Manager plug-in. A development environment consists of the following components: n The SAS Customer Intelligence Studio interface for building campaigns n SAS Decision Services Design Server n SAS Web Application Server n SAS Federation Server n SAS Metadata Repository n SAS Management Console

Test and Production Environments From a software topology perspective, the test and production environments are identical. The production environment provides the capabilities and performance required for continual operation, twenty-four hours a day, every day of the year. As with the development environment, decision flows and their building blocks are stored in a repository. Repositories and their contents are managed by the Decision Services Manager plug-in or client application plug-ins. An important function of the Decision Services Manager plug-in (within the test and production environments) is to activate or deactivate decision flows. Activating or deactivating decision flows either connects or disconnects decision flows with operational channels or systems. A test or production environment consists of the following components: n SAS Decision Services Engine Server cluster and a load balancer n SAS Web Application Server containing the engine server cluster n One or more SAS Federation Servers n SAS Metadata Repository n SAS Management Console n A third-party database management system

For more information about the components in test and production environments, see “Operational Middle Tier for SAS Real-Time Decision Manager Server or SAS Real-Time Decision Manager Run-Time Server” on page 45.

Choosing Environments At a minimum, install one development and one production environment. You can install one or more test environments, depending on your organization's testing policies. Decision flows can be unit tested in the development environment. A test environment is used to test decision flows in an environment that is similar to production. The test and production environments have only a few differences: n The test environment is not connected to live channels or customer-facing

systems.

52 Chapter 2 / Architecture n More hardware and network resources might be allocated to the production

environment. The development environment is typically not clustered. The production environment might use a clustered middle tier, database tier, and SAS Federation Server tier.

A Typical Configuration A typical installation consists of development, test, and production environments, although the number of environments is configurable to accommodate process standards that reference internal approval. Decision flows are created and functionally tested in the development environment by business s. When a business is satisfied that a decision flow is ready for deployment, an promotes the flow to either a test or production environment. A test environment is optional and can be used to conduct performance testing on decision flows in an environment that is similar to the production environment. The production environment serves live channels or customer-facing systems. Each environment includes a repository of decision flows, their building blocks, and other resources. In SAS Customer Intelligence Studio, you can use the Deployment category in the istration workspace to promote artifacts from one repository to another repository. For more information, see “Managing Deployments” on page 229. You can also use the SAS Management Console import and export functionality to promote artifacts. For more information, see “Importing and Exporting SAS Packages” on page 222. In these cases, decision flows and other artifacts are promoted between development, test, and production environments. The Decision Services Manager plug-in also operates on these repositories and is used to monitor and control SAS Decision Services run-time systems from a central location. After a flow is promoted, you can use the Deployment category in SAS Customer Intelligence Studio or the Decision Services Manager plug-in to activate the flow, putting it into production. For more information, see “Activating and Deactivating Selected Campaigns” on page 243. You can also use the SAS Decision Services istrative API to automate activation. For more information, see Appendix 7, “SAS Decision Services istration,” on page 443.

Life Cycle of a Decision Campaign Overview The following examines the stages of the decision flow life cycle.

Development and Testing Use SAS Customer Intelligence Studio to create campaigns that direct communications to a selected group of customers. After you create a campaign, you use the diagram and nodes to create a decision flow. The decision flow determines which reply will be sent to the customer through the communication

Life Cycle of a Decision Campaign

53

channel. Test the campaign by executing it using the test data in the Test mode in SAS Customer Intelligence Studio. The SAS Decision Services Design Server executes the campaign logic and activities during this stage in the same way that the SAS Decision Services Engine Server executes the campaign in production.

Mark the Campaign for Deployment the test data and then mark the campaign for deployment in SAS Customer Intelligence Studio or SAS Management Console. SAS Decision Services deployment must include a development environment and a production environment. One or more test environments can be included as well. In this context, a test environment is just like a production environment except that it is not connected to live channels. The type of testing that is performed depends on company policy. Examples include performance testing and ing flow results over a large set of sample inputs. Each environment (development, test, and production) has an associated repository. When you mark a campaign for deployment, the campaign is persisted as a decision flow in the SAS Decision Services Design Server repository and is published to the common data model. If the campaign is marked for deployment more than once, then the new copy of the decision flow overwrites any previous copy. When the flow is persisted, the takes control of the decision flow. The works primarily within SAS Management Console.

Promotion Use the Deployment category in SAS Customer Intelligence Studio to promote the campaign by exporting the campaign from the SAS Decision Services Design Server repository and importing it into a test or production repository. You can also use SAS Management Console to promote, or manually deploy, the campaign. You might want to initially promote the campaign to a test repository to the results. For more information, see “Deploying and Undeploying Selected Campaigns” on page 237. DS2 packages, which implement SAS activity methods, should be promoted to production less frequently than campaigns. Promoting DS2 packages every time a campaign is promoted can break decision flows that used older versions of activities. When you consider whether to promote a DS2 package, keep in mind the potential impact this might have on existing campaigns in production that use the same DS2 package code.

Activation Each decision flow in a test or production environment is either active or inactive. Only active flows are loaded by a SAS Decision Services Engine Server. To make a flow ready to process events (or to make it ready for testing in a test environment) the must activate it. To remove a flow from production, the deactivates it. For more information, see “Activating and Deactivating Selected Campaigns” on page 243. Note: In SAS Real-Time Decision Manager, all of the activities in a single flow execution are executed one at a time, rather than concurrently. When used for

54 Chapter 2 / Architecture arbitration, treatment campaigns in a treatment campaign set are executed concurrently each time the parent campaign is run.

Monitoring The SAS Decision Services Monitor provides an API for querying activity hit counters and execution performance statistics. The Monitor also controls production batch execution, and provides access to batch job progress, status, and results. For more information, see “SAS Decision Services Monitoring” on page 279.

SAS Decision Services Repositories SAS Decision Services Repositories and Metadata Objects A SAS Decision Services content repository can be viewed in SAS Management Console by using either the Folders view or the Decision Services Manager plug-in. In the Folders view, all Decision Services objects are shown, and each has an associated name, description, type, and modification date. In the Decision Services Manager plug-in, the folder hierarchy displays a context-sensitive view of the repository and provides product-specific functionality. Only the object types that can be manipulated by the plug-in are displayed. By contrast, the Folders tab displays a non-context-sensitive view that works with any product. Although rendered differently, both options display the same data. Repositories contain decision flows and their building blocks. These building blocks include events, activities, global variables, and system resources. You specify a repository as a development, testing, or production repository. The SAS Decision Services repositories contain the following metadata objects: n activities (

)

n decision flows ( n events (

)

)

n global variables ( n system resources (

) )

For more information about the objects, see “Metadata Objects in the SAS Repositories” on page 56. A repository does not have to be associated with a server; it can be used simply as a storage area for the objects. A repository resides in SAS Metadata Repository. However, each Decision Services development, test, and production environment maintains a repository where the objects of the environment are kept.

SAS Decision Services Repositories

55

During installation of SAS Real-Time Decision Manager, a number of metadata objects are automatically installed in the SAS Decision Services design repository in SAS Management Console. Figure 2.6 Repository Objects

When a marks a campaign, treatment campaign set, or treatment campaign for deployment or tests them, SAS Customer Intelligence generates a decision services flow. This flow contains the SAS Decision Services code that is used to implement the campaign. You can change the object values in the Decision Services Manager plug-in on the Plug-ins tab. You typically need to change the connection of the resource values from the test database to the live database. Right-click the resource name to change the value. For more information, see “Best Practices for Exporting and Importing Objects” on page 223. You might need to adjust your system resources in order to use the correct URLs and authentication credentials for the new environments. For more information, see “Metadata Objects in the SAS Repositories” on page 56.

Location of Files in the SAS Decision Services Repositories If you are testing campaigns in SAS Customer Intelligence Studio, metadata objects are located in the SAS Folders  System  Applications  SAS Decision Services  Decision Services 6.x  SASDSDesignRepository folder on the Folders tab. If you are executing campaigns after they have been activated, the objects must be located in the SAS Folders  System  Applications  SAS Decision Services  Decision Services 6.x  SASDSEngineRepository folder on the Folders tab. The DS2 code for the SAS processes and models is also located in the SAS Federation Server. Identifiers are located in the SAS Content Server. Identifiers and custom detail tags do not appear in the Folders tab in SAS Management Console

56 Chapter 2 / Architecture Data process definitions require SAS Libraries that are ed in the SAS Data Library Manager for selecting a table. The list of libraries is then filtered to show only those libraries in the corresponding SAS Decision Services Design repository folder for the current business context.

Create a SAS Decision Services Repository To create a new SAS Decision Services repository: 1 Log on to SAS Management Console. Select the metadata profile that is

associated with the SAS Metadata Server where you want to create your repository. For more information about metadata profiles, see the SAS Management Console Help. 2 Expand Decision Services Manager and Content Repositories. 3 Right-click the folder where you want to create your repository, and select

Create repository. 4 Choose either a development, test, or production repository. Click Next. 5 Enter a name for your new repository. Click Next. 6 Review the information for accuracy. Click Finish. 7 that your repository was created correctly by expanding your repository

folder.

Delete a SAS Decision Services Repository CAUTION! Deleting a repository is an irreversible operation.

To delete a SAS Decision Services repository: 1 Log on to SAS Management Console. Choose the metadata profile that is

associated with the SAS Metadata Server that contains the repository to delete. 2

Expand Decision Services Manager and Content Repositories. Right-click the repository that you want to delete and select Delete.

3 your intent to delete the repository by clicking Yes.

Metadata Objects in the SAS Repositories Overview Metadata objects are provided with the product and are typically configured by on-site SAS personnel when your system is installed. On-site SAS personnel can also work with your IT department to define the external events that are appropriate to your processing needs. Each external event defines the data that is exchanged between your system and SAS Decision

Metadata Objects in the SAS Repositories

57

Services for a specific interaction. An event typically consists of a set of request variables and a set of reply variables. Metadata objects are also created when you use SAS Customer Intelligence Studio to create campaigns for SAS Real-Time Decision Manager. An activity is created when you define a process other than a data process for your campaign. When you create an event or global variable in SAS Customer Intelligence Studio, a definition for the event or global variable is stored in the SAS Decision Services design repository. When you mark a campaign for deployment in SAS Customer Intelligence Studio, a flow metadata object is created in the SAS Decision Services design repository.

Activities When you create a self-learner process, a SAS process, a web process, or a model process (if you licensed SAS Model Manager) in SAS Customer Intelligence Studio, a SAS Decision Services activity is generated that can perform an operation (such as executing custom DS2, executing a model, executing a rules definition, calling a web-service, and so on). To execute the operation, you must add a Process node that references that definition to a campaign and then execute the campaign. An activity is a component of business work such as computing a credit score, or performing a market basket analysis. In SAS Real-Time Decision Manager, an activity XML is created each time you define a process for your campaign. Activities are represented as the nodes of a decision flow diagram. Each activity contains a set of actions. For example, the General I/O activity contains the actions READ, INSERT, and UPDATE. Each action contains a set of inputs and outputs that are mapped to process variables. The activities that are provided with SAS Decision Services contain a rich set of functionality. The activities within a flow can execute sequentially or concurrently as specified by the containing flow. For more information about creating campaign definitions, see SAS Real-Time Decision Manager: ’s Guide. SAS Decision Services provides a rich set of activities for constructing decision flows that automate real-time decisions and actions. Activities perform work actions, such as executing SAS programs on a SAS server, storing and accessing information from a relational database, sending web service requests to external systems, executing business rules, and executing scoring models. If your organization has a special processing need that is not covered by the provided activity set, new activities can be added. This is accomplished by developing custom SAS code and publishing it to the SAS Decision Services environment. The activity publishing step assembles metadata. Metadata is necessary in order for the activity to be recognized by a SAS Decision Services engine and to be rendered and tested in a client environment, such as SAS Customer Intelligence Studio or SAS Enterprise Decision Manager. The interface that is used to publish activities is provided by the SAS solution, such as SAS Customer Intelligence, which in turn makes SAS Decision Services API calls in order to publish a new activity. SAS Decision Services uses the following classifications of configurable activities: n SAS activity n web service activity

58 Chapter 2 / Architecture For more information, see “Integrating with External Web Services” on page 161. n general I/O activity

For more information, see “General I/O Activities” on page 65. The SAS activity type is used to host score code and business rules. It is also used to extend SAS Decision Services functionality. A SAS activity consists of a SAS program and an activity XML document that describes the activity, the methods that are ed by that activity, and the system resources that are used by that activity. SAS Decision Services functionality can be extended with custom activities. You can write a custom activity in the DS2 programming language, test it in a SAS session, and publish it to SAS Decision Services, where it can be included in decision flows. DS2 programming skills are required to develop SAS code that runs as an activity. For assistance with custom activity development or publishing, your on-site SAS personnel. SAS Decision Services stores DS2 source code in the activity metadata, using XML tags for DATA step and DS2 code that have been added to the activity schema. This feature enables the engine to automatically publish activity code as needed, guaranteeing referential integrity, and ensuring the decision services repository accurately represents the deployed code.

Events An event represents an action that triggers the decision process, such as a customer call to a hot line to request product information. In SAS Customer Intelligence Studio, you use the Decision category in the Definitions workspace to define a web service event to determine the variables that begin a diagram flow. You then use a Start node in a diagram to select the event that you have defined. The SAS Decision Services Engine web service accepts messages called events. Each request for a decision is presented to the system as an event. These events and their associated decision flows are presented to external clients as web services. An event definition specifies a request message format and a reply message format. Events that are designed only to receive information can omit the reply message. An event makes up the contract between an external system and a decision flow, specifying the types of information that is contained within the request and reply. Typically, your IT department sets up your systems to make web service requests to the SAS Decision Services Engine, and on-site SAS personnel define the events that map the data. Events and global variables are shared across business contexts that point to the same SAS Decision Services repository. In those instances, events or global variables that are created in one business context appear in the Events and Global Variables tables in only the business contexts that share the same SAS Decision Services design repository. If you want to separate events and global variables between business contexts in the design repository, then you must specify a separate SAS Decision Services repository on the Settings tab for each business context. For more information, see “Data Options Settings for Decision Campaigns” in SAS Real-Time Decision Manager: ’s Guide, or SAS Technical at https://.sas.com/techsup//.


59

The following table lists and describes the default events that are automatically generated in the SAS Decision Services design repository by SAS Customer Intelligence Studio. Table 2.1

_SAS_ Events

Event Name

Description

_SAS_ADD_STAGED_TREATMENTS_EVENT

Add staged treatments event

_SAS__HISTORY_EVENT

history event

_SAS_DYNAMIC_TREATMENT_EVENT

Dynamic treatment event

_SAS_PRESENTED_TREATMENT_EVENT

Presented treatment event

_SAS_REMOVE_STAGED_TREATMENTS_EVENT

Remove staged treatments event

_SAS_RESPONSE_HISTORY_EVENT

Response history event

_SAS_RETRIEVE_STAGED_TREATMENTS_EVENT

Retrieve staged treatments event

When the SAS Customer Intelligence Studio creates an event or a global variable, the definition is stored in a SAS Decision Services design repository. You display the code by right-clicking the event or variable and selecting View SAS Decision Services content. Figure 2.7 Event Definition

A response to an event is called an EventResponse. The XML payload for the event contains a name field, a header, and a body. The name field contains the name of the event definition that is used to find the flow to execute. This header is distinct from the envelope header. The EventResponse also contains a header and a body. The event header contains the following data items: Identity This is a string value that can be used to identify the event. The engine does not interpret the value of this field. However, it is logged in the engine log when there are faults or when trace logging is enabled. Although the engine does not enforce the uniqueness of this value, it is recommended that a

60 Chapter 2 / Architecture unique value be provided for every call to track issues. This value is also returned as the value of the correlation ID for the EventResponse. The method getEventIdentity() returns the value of this input header element. ClientTimeZoneId This is a string value that contains the time zone ID of the client that is calling the engine. This value is used by certain SAS Decision Services functions to interpret date and time values that do not contain the time zone information. The valid values of this field are the time zone IDs that are ed by Java, and are based on the IANA time zone database. The method getEventIdentity() returns the value of this input header element. SimulationDate This is an optional element that has two attributes: date, an XML datetime, timeZoneID, a string. The valid values for the time zone ID are the same as described in ClientTimeZoneID. If the SimulationDate element is not present, the default is the value of the StartTime element, returned in the event output header, plus the value of the input header element ClientTimeZoneID. The method getEventSimulationDate() returns a calendar that is constructed from these values. The event response header contains the following data items: CorrelationId This is a string field that contains the value of the Identity field of the event. StartTime This is a timestamp that shows when the message was received by the engine. CompletionTime This is a timestamp that shows when the engine finished processing the event. Body The body contains data that is the input for, or output of, the engine when it is executing a specific event. The schema for this section is generic. Depending on the requirements of the EventDefinition, this section might contain zero or more data items that contain the input or output values. In some cases, you might want to allocate a longer processing time to an event. You can change the time-out setting for the following events. For more information, see “Set an Event Time-Out in SAS Management Console” on page 84.

Flows A flow (also called a decision flow) defines the set of decisions and actions to take when a third-party system, such as a website or a call center, sends a request to SAS Decision Services. A decision flow includes activities and business logic that determines the order in which the activities are processed. Each individual type of request has one decision flow that is associated with it. Multiple copies of each decision flow can process multiple requests concurrently and are available to field a high volume of transactions. When a marks a campaign, treatment campaign set, or treatment campaign for deployment or tests them, SAS Customer Intelligence generates a decision services flow. This flow contains the SAS Decision Services code that is used to implement the campaign. When one campaign calls another campaign via a sub-diagram node, the code that Customer SAS Intelligence generates has one


61

decision services flow calling to another decision services flow. Similarly, the decision services flows that are generated for SAS Customer Intelligence treatment campaign sets or for treatment campaigns call each other. These types of call-outs are often referred to as sub-flows. Sub-flows can also refer to utility decision services flows that are called by the decision service flows generated for a campaign. The sub-flow used to call the history webservice is an example of such a sub-flow. These flows begin with _SAS_*. In the engine, the history flow that is used is determined by which flow is marked Active. There are no distinctions between flows and sub-flows other than the fact that sub-flows are called by other flows. Sub-flows are event-driven like any other flows. To invoke a sub-flow, the includes a sub-flow activity that enables the to select the event that drives the desired sub-flow, and to map the event request and reply fields to process variables in the parent flow. A sub-flow within a particular flow might execute sequentially or concurrently, depending on how the parent flow is configured. Here are several benefits of using sub-flows: n removing instances of duplicated code across decision services campaign

flows, which decreases the memory footprint and increases performance n enabling you to implement the same functionality (such as history)

using different flows. Switching between flows does not require you to regenerate or redeploy the decision services flows. This capability can be helpful in those instances where a web-service version of the flow cannot be used. Here are some examples of switching flows: o

_SAS__HISTORY_DS2_FLOW, _SAS__HISTORY_WS_FLOW, and _SAS__HISTORY_NULL_FLOW populate the CDM history tables. They all implement the _SAS__HISTORY_EVENT interface. Therefore, you can activate whichever flow best meets your current needs, and turn off the other flows. In this example, you might use the _SAS__HISTORY_DS2_FLOW if you wanted to update the history before the flow completes.

o

SAS_ADD_STAGED_TREATMENTS_GIO_FLOWand _SAS_ADD_STAGED_TREATMENTS_NULL_FLOW add treatments to the staging area. You can activate the GIO flow if storing the staged treatments in the CDM table and the NULL flow if you want to temporarily stop treatments from being staged. If you activate the NULL flow, the campaigns will continue to run normally, returning results to the caller, and any staged treatments will be discarded.

n Using SAS Customer Intelligence sub-diagram mode to factor out common

customer intelligence nodes into a separate campaign, and calling the separate campaign via a sub-diagram node. For example, instead of having the same 10 nodes in 50 campaigns, you can create a new campaign that has those 10 nodes, and place a sub-diagram node into each of the 50 campaigns to call that new campaign. The 50 decision services flows will all call the same decision services sub-flow. This simplifies maintenance. If the needs to make a change or fix to one of those 10 nodes, she can make the change in one place instead of in 50.

62 Chapter 2 / Architecture n simplifying campaigns so that they are easier to read. Having easily read

campaigns, diagrams, and sub-diagrams reduces errors and later maintenance issues n improving the flexibility of your campaign by enabling you to edit and promote

sub-diagrams without having to edit or promote the entire campaign n increasing the reusability of sub-diagrams for segments of logic (such as

Compute Propensity Scores, Determine Credit Score, and so on) Web service, general IO, and DS2 activities are generated as packaged subflows (that is, flows that are invoked by other flows) that call the pertinent events. Sub-flows recursive composition that enables complex flows to be produced by combining simpler, easier-to-understand flows that perform a targeted set of tasks.You can deploy and activate different versions of these flows independently of the campaign flows. All flows are available for activation in the engine repository. If flows share the same event, only one flow can be active. Activating one flow deactivates the previously active flow. If you activate an empty flow, records are no longer written. For example, if the history table is corrupted, you can activate _SAS__HISTORY_NULL_FLOW to stop writing history. The following tables lists and describes the flows that are called by campaigns that are automatically generated by SAS Customer Intelligence Studio. Table 2.2

_SAS_ Flows

Flow Name

Description

_SAS_ADD_STAGED_NULL_FLOW

Empty add staged treatment flow

_SAS_ADD_STAGED_TREATMENTS_GIO_FLOW

Add staged treatments general IO flow for staging into the common data model or a customized staging mechanism

_SAS__HISTORY_DS2_FLOW

history DS2 flow

_SAS__HISTORY_NULL_FLOW

Empty history flow

_SAS__HISTORY_WS_FLOW

history web service flow

_SAS_DYNAMIC_TREATMENT_DS2_FLOW

Dynamic treatment DS2 flow

_SAS_DYNAMIC_TREATMENT_NULL_FLOW

Empty dynamic treatment flow

_SAS_DYNAMIC_TREATMENT_WS_FLOW

Dynamic treatment web service flow

_SAS_PRESENTED_TREATMENT_DS2_FLOW

Presented treatment DS2 flow

_SAS_PRESENTED_TREATMENT_NULL_FLOW

Empty presented treatment flow

_SAS_PRESENTED_TREATMENT_WS_FLOW

Presented treatment web service flow

_SAS_REMOVE_STAGED_NULL_FLOW

Empty remove staged treatment flow


63

_SAS_REMOVE_STAGED_TREATMENTS_GIO_FLOW

Remove staged treatments general IO flow from the common data model or a customized staging mechanism

_SAS_RESPONSE_HISTORY_DS2_FLOW

Response history DS2 flow

_SAS_RESPONSE_HISTORY_NULL_FLOW

Empty response history flow

_SAS_RESPONSE_HISTORY_WS_FLOW

Response history web service flow

_SAS_RETRIEVE_STAGED_NULL_FLOW

Empty retrieve staged treatments flow

_SAS_RETRIEVE_STAGED_TREATMENTS_GIO_FLOW

Retrieve staged treatments general IO flow

For more information, see “Activating and Deactivating Selected Campaigns” on page 243.

Global Variables In SAS Customer Intelligence Studio, you use the Decision category in the Definitions workspace to create global variables. Global variables are used to control the behavior of flows at execution time. For example, by modifying the value of a global variable that contains a customer risk threshold, the boundary between a medium-risk customer versus a high-risk customer can be adjusted at run time without changing any expressions or redeploying the flow. For information about creating global variables in SAS Customer Intelligence Studio, see SAS Real-Time Decision Manager: ’s Guide. For information about managing global variables in a SAS Decision Services repository, see “Managing Global Variables in SAS Management Console” on page 89. Unlike process variables, global variables are Read-only with respect to flows and are cluster scoped rather than flow scoped. The value of a global variable affects the behavior of every flow within an engine server cluster that references the global variable.

Predefined Global Variables Overview of Predefined Global Variables SAS Real-Time Decision Manager provides predefined global variables that help you manage test behavior and set the delimiters for SAS Decision Services runtime flows. Like other global variables, predefined global variables are selectable on the Global Variables tab of the test interface and in the Global Variables category in the Definitions workspace in SAS Customer Intelligence Studio. For more information, see SAS Real-Time Decision Manager: ’s Guide. Changing the value of a global variable through SAS Management Console affects the value of that variable in all flows.

Manage Test Behavior The following predefined global variables affect test behavior.

64 Chapter 2 / Architecture _SAS_LIST_REMOVED_STAGED_TREATMENTS When set to True, this variable enables you to review staged treatments that were removed during testing. Select the Remove Staged node to view the removed treatments on the Treatments tab. The default value is False. _SAS_RECORD_HISTORY When set to True, this variable writes history records to the common data model. History processes are prepared and validated during testing. When set to False, history processes are prepared and validated during testing, but the records are not written to the common data model. The default value is True. _SAS_STAGING_VARIABLE This variable enables you to use subject IDs to share data between individual tests in production, or to process isolated data. The default value for test cases is the ID of the who is currently logged on. The initial production value is generated during installation. The purpose of this variable is to prevent s of the SAS Real-Time Decision Manager test interface from interfering with each other or the flows running in production. In production, the default value that was generated at installation time for _SAS_STAGING_VARIABLE is used. In this case, if one flow stages a treatment for a client, then any other flow that picks up the staged treatments for that client would see the treatment that was staged by the first. Both testers might be staging treatments for the same client and depending on the tests, each of the testers’ flows that picked up staged treatments might see the treatments staged by the other tester in addition to their own, or might not see any treatments at all. To prevent this, from the test interface, the default for the _SAS_STAGING_VARIABLE must be set to the ID. When the variable is set to the ID and multiple s are using the test interface, a tester can view only the treatment that he staged, and the other tester would view only the treatments that she staged. If they want to see each other’s staged treatments in the test interface, they must override the default setting and both set the _SAS_STAGING_VARIABLE to the same value. This variable is also used is when the staging table that is used in production is the same as that used by test so that the treatments staged during testing do not interfere with the production flows retrieving staged treatments. Because the _SAS_STAGING_VARIABLE value used in production is different from that used by default by the test interface, the treatments staged during testing will never be seen by flows that are run in production.

Specify Separators The following predefined global variables set the delimiters that are used by SAS Decision Services run-time flows. _SAS_CAMPAIGN_TREATMENT_SEPARATOR The delimiter that separates treatments. _SAS_CCS_VALUE_SEPARATOR The delimiter that separates treatment custom detail values when using the web service method for updating history. Note: This delimiter is not used for DS2 history updates _SAS_CAMPAIGN_LIST_SEPARATOR The delimiter that separates lists.

General I/O Activities

65

System Resources System resources are artifacts that provide activities with access to external resources within their environment, such as relational databases, SAS servers, or web services. For example, many activities rely on running a SAS DS2 program to produce results. Because flows execute in SAS Web Application Server in the middle tier, these activities must communicate with SAS Federation Servers. The fact that activities reference system resource information (rather than contain system resource information) makes flows portable between systems. SAS Decision Services s configurable design, test, and production environments. Typically, the set of SAS Federation Servers that is used by development and production environments is different. System resources enable the correct set of servers to be used in each environment without modification to the decision flow.

Library Resources Library resources are special optional system resources that can assist database operations in certain circumstances. Library resources can hold an alias to a database schema name, allowing the alias name to be used to access tables within the schema. Library resources are optional and are not required for SAS Decision Services operation.

General I/O Activities Overview SAS Decision Services is shipped with a General I/O activity that can read or write to any ed database table or SAS data set. A General I/O activity uses a JDBC Connection resource. This resource specifies which database the activity uses. At least one JDBC Connection resource was configured when your system was installed. Note: SAS data sets exhibit file-level locking. If multiple threads of execution attempt to simultaneously read from or write to a SAS data set, deadlocks can occur. Therefore, the use of a relational database management system is highly recommended for real-time (non-batch) processing. A system-level time zone can be used when reading or writing date and time from a database using General I/O activity. To interpret the value in the database or to write a timestamp objects to the database, you must supply a time zone value. The time zone ID is supplied as the value of the two system properties sasds.designserver.default.timezoneid and sasds.engine.default.timezoneid, for design server and engine respectively. If the value is not set, the default is Greenwich Mean Time (GMT). If the supplied value is not a valid time zone ID, then an error is logged and the GMT value is used instead.


Operations Read Method name: SCReadTable. Properties G_IO_WHERE_Clause - WHERE clause. The WHERE clause property is a static string that is set on the General I/O Activity instance when it is inserted into a flow. A WHERE clause is a SAS Decision Services (not SQL) Boolean expression. Logical (AND, OR, NOT), relational (EQ, NE, GT, GE, LT, LE), and arithmetic (+, -, /, *) operators can be used. Here is an example: CustomerInfo.Income GT 50000.0. As in a DATA step, a . (period) denotes a missing value. Note: To ignore trailing blanks, use the operators SQL_EQ, SQL_NE, SQL_GT, SQL_GE, SQL_LT, SQL_LE. These operators are valid only for strings. Process parameters can be referenced as :{Process parameter name}. Here is an example: CustomerInfo.LastName EQ :PV_CustomerLastName Note: '=' and '!=' are not ed in General I/O WHERE clauses. EQ and NE are used instead. Input Parameters n G_IO_libraryName - Library or schema name. n G_IO_tableName - Database table name.

Input and Output Parameters G_IO_Result_Table Result - SAS Decision Services table. On input, this table contains column definitions (name and type). The specified columns are selected from the database, and coerced to the specified type if possible. On output, this table contains the original column definitions plus rows of data that are selected from the database.

Insert Method name: SCInsertIntoTable. Input Parameters n G_IO_libraryName - Library or schema name. n G_IO_tableName - Database table name. n G_IO_Insert_Values - A SAS Decision Services table that contains

multiple rows. Corresponding rows are inserted in the database table. Columns that occur in the database but not in this table are set to null or missing. Input and Output Parameters None.

Update Method name: SCUpdateTable.


67

Properties G_IO_WHERE_Clause - WHERE clause. The WHERE clause property is a static string that is set on the General I/O Activity instance when it is inserted into a flow. A WHERE clause is a SAS Decision Services (not SQL) Boolean expression. Logical (AND, OR, NOT), relational (EQ, NE, GT, GE, LT, LE), and arithmetic (+, -, /, *) operators can be used. Here is an example: CustomerInfo.Income GT 50000.0. As in a DATA step, a . (period) denotes a missing value. Note: To ignore trailing blanks, use the operators SQL_EQ, SQL_NE, SQL_GT, SQL_GE, SQL_LT, SQL_LE. These operators are valid only for strings. Process parameters can be referenced as :{Process parameter name}. Here is an example: CustomerInfo.LastName EQ :PV_CustomerLastName Note: '=' and '!=' are not ed in General I/O WHERE clauses. EQ and NE are used instead. Input Parameters n G_IO_libraryName - Library or schema name. If this parameter is blank, the default database schema is used. The JDBC Connection resource that is specified in the General I/O activity definition is used. Otherwise, if a JDBC library resource that has the given name is found, that resource is used to get the database schema name and JDBC Connection resource name. If the schema name in the resource is blank, the default database schema is used. If a JDBC library resource with a given name is not found, the name is interpreted directly as a database schema name. The JDBC Connection resource that is specified in the General I/O activity definition is used. Prior to SAS Decision Manager 5.5, this parameter specified a SAS libref. This name did not correspond to an actual database schema name. If your installation is earlier than 5.5, it can retain this name, but must add a JDBC library resource that has the same name. That resource can specify the database schema name. n G_IO_tableName - Database table name.

A table name in the database schema (default or specific) that is specified by this G_IO_libraryName. n G_IO_Update_Values - A SAS Decision Services table that contains one

row. The table contains column definitions along with their corresponding values. Output Parameters G_IO_Rows_Updated - The number of database rows that are updated.

Insert Update Method name: InsertUpdateTable Properties G_IO_WHERE_Clause - WHERE clause. The WHERE clause property is a static string that is set on the General I/O Activity instance when it is inserted into a flow.

68 Chapter 2 / Architecture A WHERE clause is a SAS Decision Services (not SQL) Boolean expression. Logical (AND, OR, NOT), relational (EQ, NE, GT, GE, LT, LE), and arithmetic (+, -, /, *) operators can be used. Here is an example: CustomerInfo.Income GT 50000.0. As in a DATA step, a . (period) denotes a missing value. Note: To ignore trailing blanks, use the operators SQL_EQ, SQL_NE, SQL_GT, SQL_GE, SQL_LT, SQL_LE. These operators are valid only for strings. Process parameters can be referenced as :{Process parameter name}. Here is an example: CustomerInfo.LastName EQ :PV_CustomerLastName Note: '=' and '!=' are not ed in General I/O WHERE clauses. EQ and NE are used instead. Input Parameters n G_IO_libraryName - Library or schema name. If this parameter is blank, the default database schema is used. The JDBC Connection resource that is specified in the General I/O activity definition is used. Otherwise, if a JDBC library resource that has the given name is found, that resource is used to get the database schema name and JDBC Connection resource name. If the schema name in the resource is blank, the default database schema is used. If a JDBC library resource with a given name is not found, the name is interpreted directly as a database schema name. The JDBC Connection resource that is specified in the General I/O activity definition is used. n G_IO_tableName - Database table name.


row. The table contains column definitions along with their corresponding values. n G_IO_Increment_Values - A SAS Decision Services table that contains

one row. The table contains column definitions along with their corresponding values. The increment columns must be numeric. n G_IO_Insert_Values - A SAS Decision Services table that contains one

row. The table contains column definitions along with their corresponding values. Output Parameter G_IO_Rows_Updated - The number of database rows that are updated.

Increment Update Method name: IncrementUpdateTable Properties G_IO_WHERE_Clause - WHERE clause. The WHERE clause property is a static string that is set on the General I/O Activity instance when it is inserted into a flow. A WHERE clause is a SAS Decision Services (not SQL) Boolean expression. Logical (AND, OR, NOT), relational (EQ, NE, GT, GE, LT, LE), and arithmetic


69

(+, -, /, *) operators can be used. Here is an example: CustomerInfo.Income GT 50000.0. As in a DATA step, a . (period) denotes missing. Note: To ignore trailing blanks, use the operators SQL_EQ, SQL_NE, SQL_GT, SQL_GE, SQL_LT, SQL_LE. These operators are valid only for strings. Process parameters can be referenced as :{Process parameter name}. Here is an example: CustomerInfo.LastName EQ :PV_CustomerLastName Note: '=' and '!=' are not ed in General I/O WHERE clauses. EQ and NE are used instead. Input Parameters n G_IO_libraryName - Library or schema name. If this parameter is blank, the default database schema is used. The JDBC Connection resource that is specified in the General I/O activity definition is used. Otherwise, if a JDBC library resource that has the given name is found, that resource is used to get the database schema name and JDBC Connection resource name. If the schema name in the resource is blank, the default database schema is used. If a JDBC library resource with a given name is not found, the name is interpreted directly as a database schema name. The JDBC Connection resource that is specified in the General I/O activity definition is used. n G_IO_tableName - Database table name.


row. The table contains column definitions along with their corresponding values. n G_IO_Increment_Values - A SAS Decision Services table that contains

one row. The table contains column definitions along with their corresponding values. The increment columns must be numeric. n G_IO_Rows_Updated – The number of database rows that are updated.

Delete Method name: DeleteFromTable Properties G_IO_WHERE_Clause - WHERE clause. The WHERE clause property is a static string that is set on the General I/O Activity instance when it is inserted into a flow. A WHERE clause is a SAS Decision Services (not SQL) Boolean expression. Logical (AND, OR, NOT), relational (EQ, NE, GT, GE, LT, LE), and arithmetic (+, -, /, *) operators can be used. Here is an example: CustomerInfo.Income GT 50000.0. As in a DATA step, a . (period) denotes a missing value. Note: To ignore trailing blanks, use the operators SQL_EQ, SQL_NE, SQL_GT, SQL_GE, SQL_LT, SQL_LE. These operators are valid only for strings. Process parameters can be referenced as :{Process parameter name}. Here is an example: CustomerInfo.LastName EQ :PV_CustomerLastName

70 Chapter 2 / Architecture Note: '=' and '!=' are not ed in General I/O WHERE clauses. EQ and NE are used instead. Input Parameters n G_IO_libraryName - Library or schema name. If this parameter is blank, the default database schema is used. The JDBC Connection resource that is specified in the General I/O activity definition is used. Otherwise, if a JDBC library resource that has the given name is found, that resource is used to get the database schema name and JDBC Connection resource name. If the schema name in the resource is blank, the default database schema is used. If a JDBC library resource with a given name is not found, the name is interpreted directly as a database schema name. The JDBC Connection resource that is specified in the General I/O activity definition is used. n G_IO_tableName - Database table name.

A table name in the database schema (default or specific) that is specified by this G_IO_libraryName. n G_IO_Rows_Deleted - (Optional) The number of database rows that are

deleted.

General I/O Write and SAS Data Sets SAS data sets do not concurrent updates. Therefore, locking errors can occur if you try to use General I/O to insert records into a SAS data set or to update records in a SAS data set. If concurrent writes are required, then use a database table. If a data set is opened in an interactive SAS session while SAS Decision Services is reading the data set, locking errors occur. The errors occur because SAS locks the file when it is opened. It is recommended that all other SAS data sets be closed in an interactive SAS session while SAS Decision Services is using the SAS data set.

Stored Processes A stored process is a SAS program that is stored on a server and can be executed as required by requesting applications. The following table lists the stored processes for SAS Real-Time Decision Manager. Table 2.3

Stored Processes

Stored Process

Action

ma_cdi_update_ch (CHUpdate)*

updates history

ma_cdi_update_dt (DTUpdate)*

updates treatment history (dynamic treatments)

Dependent SAS Products

71

Stored Process

Action

ma_cdi_update_pt (PTUpdate)*

updates presented treatments

ma_cdi_update_rh (RHUpdate)*

updates response history

ma_create_batch (ma_create_batch)

creates batch simulation data sets

ma_validate_ (MA_Validate_)

validates bulk-load settings in the business context

ma_publish (MAPublish)

publishes campaign information to the common data model

madatagrid (DataGrid)

renders or transmits data grids for use in the test interface

ma_self_learner.sas (MA_Self_Learner)

generates self-learning model code

ma_staged_count.sas (MA Staged Count)

counts staged treatments in common data model repository

* This stored process is used only for the web service method for updating history.

Dependent SAS Products SAS Web Application Server SAS Web Application Server is a lightweight server that provides enterpriseclass features for running SAS web applications. The server is based on VMware vFabric tc Server. By packaging the server and software that can automate server configuration tasks, SAS simplifies the demands for managing a web application server. For more information, see SAS Intelligence Platform Middle-Tier ’s Guide

SAS Web Infrastructure Platform Data Server SAS Web Infrastructure Platform Data Server, the default database server for SAS Decision Services, is used to store the monitoring data that is collected during real-time and batch execution of flows on the engine server.

SAS BI Web Services for SAS 9.4 SAS BI Web Services for SAS 9.4 enables you to select a set of stored processes in SAS Management Console and use the Web Service Maker to deploy them as web services. The Web Service Maker generates a new web service that contains one operation for each stored process that you selected. For more information about developing web services, see SAS BI Web Services Developer’s Guide.

72 Chapter 2 / Architecture To invoke a SAS BI web service from SAS Decision Services, include a web service activity in your decision flow. SAS BI Web Services are useful if you want to execute DATA or PROC steps, or if you want to use SAS macro code. However, keep in mind that these code constructs carry significant performance penalties.

SAS Federation Server The SAS Federation Server is a compute server that executes SAS Decision Services activities that are written in the DS2 programming language. The SAS Real-Time Decision Manager Engine creates a direct JDBC connection to a ed database by using standard JDBC drivers that are placed in the engine. When you access data from a SAS process, that is, a DS2 node, the DS2 code in the SAS process runs in the SAS Federation Server and from there accesses data from the database. SAS Federation Server can also use DS2 code to record history transactions. For more information, see “Activate a History Process” on page 270 SAS Federation Server accesses the lookup tables produced by SAS Business Rules Manager, an optional component for SAS Real-Time Decision Manager. SAS Business Rules Manager enables you to create business rules, connect those rules together into rules flows, and publish the rule flows for use by other applications. SAS Business Rules Manager provides the ability to import lookup tables and reference them from rules. SAS Federation Server Manager is used to configure and manage the SAS Federation Server DSNs and data services. For more information, see SAS Federation Server: ’s Guide.

DataFlux Secure If you use SAS/SECURE for your SAS servers, then you must license DataFlux Secure. The reason is that encryption must be set consistently across all SAS server components. For example, if you use AES encryption for SAS Metadata Server, then all SAS servers must be configured with AES encryption.

SAS Environment Manager SAS Environment Manager is a web-based istration solution that can be used to monitor hit counters, flow performance, and system heath information. Using the SAS Decision Services HQ Plug-in for SAS Environment Manager, you can collect engine performance data, such as event hit counts, node hit counts, and average flow response time. In order for SAS Environment Manager to access the SAS Decision Services monitoring plug-in, a SAS Environment Manager agent must be installed on each server in a SAS Decision Services Engine cluster. For more information, see “Data Collection for Performance Analysis” on page 283.

Applications for Recording History You can use DS2 activities or the web service method to recording history. In general, the DS2 activities method records history faster than other methods. If you are using the web service method for recording history,

Connection Points in the SAS Real-Time Decision Manager Architecture

73

CustIntelReporting can record history transactions when it receives messages from the engine server each time the engine server has history that it must record. If you use web services for history tables, stored processes are used instead of DS2 code. For more information, see “Activate a History Process” on page 270.

Connection Points in the SAS Real-Time Decision Manager Architecture Install Types When you deploy SAS, you can automatically install and configure SAS RealTime Decision Manager in a development environment or an operational environment. Figure 2.8 Installation Types for SAS Real-Time Decision Manager

Development Install Type (Development and/or Test)

Operational Install Type (Test or Production) Cloud

1

3

SAS Customer Intelligence – create objects and campaigns 2

SAS Decision Services

6 4

Call Center Web Email Mobile IVR POS/ATM


1

Metadata Server

SAS Decision Services

4 2

5

Metadata Server

Web service

3


You use the development installation type for the development environment, the test environment, or both the development and test environments. If you use the development installation type, campaigns are executed in the following order. 1

Campaigns and campaign objects are created in SAS Customer Intelligence Studio.

2

The campaigns and campaign objects are saved as metadata objects in the metadata server.

3 The execution of the campaigns as flows is initiated in the SAS Decision

Services Design Server. The SAS Decision Services Design Server executes campaigns that are being executed within the development environment in SAS Customer Intelligence Studio. You use SOAP or a REST API to send an event to the SAS Decision Services Engine Server, which then executes a flow. 4 To execute flows, the SAS Decision Services server communicates with SAS

Metadata Server.

74 Chapter 2 / Architecture 5

If DS2 code is required in the execution of the flows, SAS Decision Services communicates with SAS Federation Server.

6 After SAS Decision Services completes the execution of the flows, the results

are returned to the interface in SAS Customer Intelligence Studio. You typically use the operational installation type if you want to simulate production as closely as possible. The operational installation type does not include SAS Customer Intelligence Studio interface or the SAS Customer Intelligence middle-tier applications. If you use the operational installation type, campaigns are executed in the following order. 1

The customer channel sends a web service request to the SAS Decision Services Engine Server to initiate the execution of flows.

2

To execute flows, the SAS Decision Services server communicates with SAS Metadata Server.

3

If DS2 code is required in the execution of the flows, SAS Decision Services communicates with SAS Federation Server.

4 After SAS Decision Services completes the execution of the flows, the results

are returned to the customer channel.

Campaign Execution Flow About the Components in a Campaign Execution Flow SASServer6, a web application server, contains SAS Customer Intelligence Core and SAS Customer Intelligence Studio. It might also contain the optional CustIntelReporting component. You can use CustIntelReporting or DS2 activities to write history transactions to the common data model. For more information, see “Activate a History Process” on page 270. SASServer7, another web application server, contains SAS Decision Services Server, SAS Decision Services Engine Server, SAS Decision Services Monitor, and SAS Decision Services istration. SAS Customer Intelligence Core sends data to the SAS Customer Intelligence Studio interface, which then displays the data as flow diagrams. The metadata server is a central repository of metadata for SAS Customer Intelligence Studio.


75

Order of the Campaign Execution Flow Figure 2.9 Campaign Execution Flow SAS Metadata Server

3a

Auto-generated event objects 4 3b

XML flows streamed

SASServer6 SAS Customer Intelligence Core

SAS Customer Intelligence Studio Test interface

Provide UI 1 7

2

SASServer7 SAS Decision Services Design Server

5

SAS Decision Services Engine Server

6

SAS Customer Intelligence Studio

SAS Decision Services Monitor

(optional) CustIntelReporting Component

SAS Decision Services istration

Here is the order of the flow for the execution of a campaign. 1 SAS Customer Intelligence Studio communicates with the web browser when

a campaign is executed in the test interface. 2 SAS Customer Intelligence Studio sends a message regarding the campaign

execution to SAS Customer Intelligence Core. 3 SAS Customer Intelligence Core creates XML flows that are streamed to the

SAS Decision Services Design Server and sends autogenerated event objects to the metadata server. 4

The SAS Decision Services Design Server requests all required metadata objects from SAS Metadata Server.

5 The SAS Decision Services Design Server executes the flows and then

sends data back to SAS Customer Intelligence Core. 6

SAS Customer Intelligence Core sends the data to SAS Customer Intelligence Studio.

7

The data is displayed as a flow diagram in the SAS Customer Intelligence Studio interface.


Database Connection Points Figure 2.10

Database Connection Points

JDBC Connections DBMS A

SASServer7 SAS Decision Services Design Server and/or SAS Decision Services Engine Server JDBC Connections

DBMS B SAS Metadata Server $General_IO_Resource $General_IO_Resource

A set of JDBC connections must be available for SASServer7 to communicate with one or more databases (for example, DBMS A and DBMS B). The parameters for these connections, such as the desired number of connections and the length of time required for holding the connections open, are set in the properties for separate $General_IO_Resource metadata objects in SAS Metadata Server. Each time you submit a query, the SAS Decision Services Design Server or SAS Decision Services Engine Server requests that the metadata provide information about connecting to the database. The metadata responds with the information that is needed to use one of the JDBC connections. The SAS Decision Services Server then uses the information to send data to the database.


77

DS2 Execution Flow Figure 2.11 DS2 Execution Flow

JDBC Connections

SASServer7 SAS Decision Services Design Server and/or SAS Decision Services Engine Server Streaming XML

SAS Federation Server Federated_DSN Base_DSN DS2_My Arbitration DS2_MyScoring DS2_MyComputation

My_DSN A B C

SAS Metadata Server $SAS_Activity_Resource (Federated_DSN information; URL (port) for SAS Federation Server)

ABC

You set the database connection parameters in the properties in the $SAS_Activity_Resource metadata object for the JDBC connections that are used to connect SAS Decision Services Design Server or SAS Decision Services Engine Server to SAS Federation Server. Custom DS2 code is stored in Base_DSN. Base_DSN is created for you by the SAS Deployment Wizard when you deploy SAS Real-Time Decision Manager. When the SAS Decision Services Server finds a node with a SAS process while it is executing the flow, it requests information about the location of the DS2 code from SAS Metadata Server. The $SAS_Activity_Resource metadata object in SAS Metadata Serverprovides the URL to the SAS Federation Server and information about the number of JDBC connections. SASServer7 uses the JDBC connections to request that SAS Federation Server execute the DS2 code (for example, DS2_MyArbitration) and return the results. SAS Federation Server sends the results back, and the SAS Decision Services Server completes the execution of the flow for the campaign. You might need to add more data source names (DSNs) that point to data that you want to access when you execute DS2 code. You must use SAS Federation Server Manager to create a Federated DSN that includes a custom Data Source Name (for example, My_DSN) that points to another database that you want the SAS Federation Server to communicate with. For more information, see SAS Federation Server Manager: 's Guide.


DS2 Publishing Flow Figure 2.12 DS2 Publishing Flow

Operating System file

Save the SAS Customer Intelligence process definition object that was created in SAS Customer Intelligence Studio.

Places DS2 package into Base_DSN location

SAS Pooled Workspace Server (stored process/PROC DS2)

SAS Federation Server Design Server queries the location of the Base_DSN in SAS Federation Server.

SAS Decision Services Design Server

SAS Customer Intelligence Studio

SAS Customer Intelligence Core

Here is the flow for publishing DS2. 1 Create a SAS process definition object in SAS Customer Intelligence Studio

and enter DS2 code in the SAS process definition. 2

SAS Customer Intelligence Studio sends information about the object and DS2 code to SAS Customer Intelligence Core.

3

SAS Customer Intelligence Core sends the information to the SAS Decision Services Design Server.

4

SAS Decision Services obtains the Base_DSN location from SAS Federation Server.

5

SAS Decision Services Design Server sends information about the SAS process object, the DS2 code information, and the Base_DSN location to the SAS Pooled Workspace Server.

6 The SAS Pooled Workspace Server runs a stored process that executes

PROC DS2 in Base SAS. 7

A DS2 package is printed to Base_DSN, and an operating system file is placed in a directory that is pointed to by the Base_DSN. If an executed campaign cannot access the most recent DS2 code that you entered in SAS Customer Intelligence Studio, check the operating system directory that is associated with Base_DSN. If the directory does not include an updated file from the time that you saved the SAS process object, the DS2 code has not been executed correctly. In that case, check the SAS Pooled Workspace Server or SAS Decision Services Design Server logs to see whether there were problems with executing the code. For more information, see “Logs for Troubleshooting” on page 322.

Integrating SAS Real-Time Decision Manager with Other SAS Products

79

Self-Learner Process Flow The self-learner process flow is shown in the following diagram: Figure 2.13 Self-Learner Process Flow SAS Customer Intelligence Studio Definitions Workspace

SAS Customer Intelligence Studio Design Workspace When definition is saved, call SAS stored process to generate model score code. Model score code stored as DS2 inside self-learner activity persisted in SAS Decision Services Design Server repository.

Self-Learner Process Definition

Campaign

Self-learner definition assigned to campaign on Treatments Scoring page. Definition applies to ALL treatments for a given marketing cell (reply node).

selects self-learner attributes: - data items (demographic data) - custom detail tags (UDFs) - subject (customer, household, etc.) - schedule (to retrain model)

Execute campaign

Common Data Model Stored Process

Save definition

SAS Decision Services Design Server Repository

Generated DATA step code

Response History

Activity Definition

Activity definition contains DS2 model code. This model code is used to generate a treatment score when the definition is assigned to a marketing cell (reply node) of a campaign in the Treatments Scoring page.

Collect data

New DATA step code

Training

Feed responses back

Schedule Stored Process to generate new model code Use collected Response History data Retrain model based on responses Generate new model code Convert new DS1 model code into DS2 Update activity persisted in SAS Decision Services Design Server repository with new DS2 model code

For more information about self-learner processes, see SAS Real-Time Decision Manager: ’s Guide.

Integrating SAS Real-Time Decision Manager with Other SAS Products SAS Business Rules Manager SAS Business Rules Manager is included with SAS Real-Time Decision Manager. SAS Business Rules Manager enables you to create business rules, connect those rules together into rules flows, and publish the rule flows for use by other applications. SAS Business Rules Manager provides the ability to import lookup tables and reference them from rules. Lookup tables are tables of key-value pairs. SAS Real-Time Decision Manager cannot directly access these lookup tables. These lookup tables have to be accessed through SAS Federation Server, which then sends the information back to SAS Real-Time Decision Manager. SAS

80 Chapter 2 / Architecture Business Rules Manager must be configured for the SAS Federation Server so that SAS Real-Time Decision Manager can access the lookup tables. For information about configuring SAS Business Rules Manager for SAS Federation Server, see SAS Customer Intelligence: Deployment Guide.

SAS Model Manager SAS Model Manager, licensed separately, can be integrated with SAS Decision Services to provide an end-to-end solution for managing and deploying analytical models into real-time operational environments. SAS Model Manager uses the same interface as SAS Decision Manager. In SAS Real-Time Decision Manager, you can define a model process that is based on the model and that can be used in decision campaigns. For more information, see “Defining the Components of Campaigns” in SAS Real-Time Decision Manager ’s Guide. See the SAS Model Manager documentation for information. This section describes the integration and interoperability between SAS Decision Services and SAS Model Manager. Scoring models are converted into SAS activities using the DSTRANS procedure. PROC DSTRANS was created to convert into DS2 code those models that SAS Enterprise Miner produced. DSTRANS is limited to a subset of SAS DATA step functionality. See PROC DSTRANS in the Base SAS Procedures Guide. Note: You cannot use the models until they are deployed on SAS Federation Server. The design environment enables a to choose any of the scoring projects that have been published to SAS Real-Time Decision Manager by SAS Model Manager. After conversion to a SAS activity through the Customer Intelligence plug-in for SAS Management Console, a scoring project can be added to a decision flow in multiple places, allowing multiple models to be included in a single decision flow. One SAS Metadata Repository folder for publishing models should be created for each design, test, and production SAS Decision Services environment in your deployment. A scoring project should be published to the design folder first and tested in the SAS Decision Services design environment.

81

3 Setting Up the Environment Customizing the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Use a Single Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Use Fully Qualified Server Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Double-Byte Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Set a Session Time-out Value for SAS Customer Intelligence Studio . . . . . . . . . 83 Set an Event Time-Out in SAS Management Console . . . . . . . . . . . . . . . . . . . . . . . 84 Prevent s from Adding Attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Enable Staging of Treatments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Set JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Lock Down a SAS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Set the Delimiter for Multiple Treatments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Set the Size of Character Fields in Batch Simulation Tables . . . . . . . . . . . . . . . . . . 88 Import the Sample Definitions and Campaign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Managing Global Variables in SAS Management Console . . . . . . . . . . . . . . . . . . . 89 Security istration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Overview of Security istration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 How the LOCKDOWN Statement Affects Campaigns . . . . . . . . . . . . . . . . . . . . . . . 92 istering SAS Identities for s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 istering Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 istering Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 istering Group and Role hip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 istering Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Modifying Access Permissions for Promoting Objects . . . . . . . . . . . . . . . . . . . . . . 108 Enable Integrated Windows Authentication in Firefox . . . . . . . . . . . . . . . . . . . . . . . 110 Additional Configuration Required When Using Integrated Windows Authentication (IWA) or Web Authentication . . . . . . . . . . . . . . . . . . . . 110 Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 WS-Security Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Standard System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 JDBC Connection System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Specify a New System Resource as a JDBC Connection . . . . . . . . . . . . . . . . . . . 123 Specify a New System Resource as a Web Service Connection . . . . . . . . . . . . 125 Specify a New System Resource as an HTTP Connection . . . . . . . . . . . . . . . . . . 126 Library Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

82 Chapter 3 / Setting Up the Environment Define a Schema Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Managing Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connection Information for the JDBC Data Source . . . . . . . . . . . . . . . . . . . . . . . . . Database Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring Additional Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Database Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configure Access to SAS Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving DS2 Persistence to a Database Management System . . . . . . . . . . . . . . Manually Configuring SAS Decision Services Monitor and Log Tables on Alternate Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

128 128 128 129 129 131 133 134 135

Creating Reporting Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Overview of Reporting Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Identify the Library for the Business Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Create a Database Shared and Domain for SAS Federation Server . . . 140 Create a Database Shared and Domain for the JDBC Connection Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Business Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Overview of Business Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Create a Business Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Asg Permissions for Business Contexts . . . . . . . . . . . . . . . . . . . . . . . . 143 Managing Permissions for s and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Setting Up Business Context Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Understanding Information Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Creating an Information Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Add Custom Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Make Custom Properties Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Add Data Item Custom Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Custom Properties (Map Level) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Deg and Testing Campaign Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Customizing the Environment Introduction See your on-site SAS personnel for installation instructions. You can also obtain useful information about the configuration of each machine, including log locations and setup scripts, in the instructions.html file for each machine where the components were installed. To view the deployment instructions for SAS Real-Time Decision Manager, including the default ports used in deployment, see the SAS Customer Intelligence: Deployment Guide at http://prod.unx.sas.com/software/ci/ index.html. To access this page, log on as ID sas, and use CI123.

Customizing the Environment

83

For information about SAS Federation Server, see SAS Federation Server: ’s Guide at http://.sas.com/documentation/onlinedoc/ fedserver/index.html.

Use a Single Install Problems often occur when different s are used for various installations and subsequent installations. To eliminate potential problems, always use the same (such as the SAS install that was specified on the preinstallation checklist) for all installations. This practice is particularly important when applying service packs. If the is running Windows Terminal Services, then you should operate in install mode.

Use Fully Qualified Server Names Specify fully qualified server machine names in the SAS Deployment Wizard of SAS Management Console in order to avoid problems that can result in connecting to the workspace and stored process servers. Table 3.1

Example of a Fully Qualified Server Name

Incorrect

joesmachine

Correct (Fully Qualified)

joesmachine.unx.mybusiness.com

Edit and correct any server machine names that are not fully qualified by modifying the server’s properties in the Server Manager folder in SAS Management Console.

Double-Byte Character Sets Text in many Asian languages requires the of double-byte character sets. In order to display this text properly in SAS Customer Intelligence tables, an option must be set in the SAS configuration file. Specify the following option in the sasv9.cfg file: -VALIDVARNAME ANY

By default, the location for sasv9.cfg is C:\Program Files\SASHome \SASFoundation\9.4\sasv9.cfg.

It is recommended to set the time zone to UTC for all servers and the encoding for SAS tiers to UTF-8.

Set a Session Time-out Value for SAS Customer Intelligence Studio By default, the HTTP session time-out value for SAS Customer Intelligence is seven days. Note: SAS applications that you use with SAS Customer Intelligence might have a different HTTP session time-out value. It is recommended that you set the time-out value for each application to match the time-out value that you set

84 Chapter 3 / Setting Up the Environment for SAS Customer Intelligence. For information about setting time-out values, see your SAS documentation. To change the session time-out value, edit these files. The path on your system is determined by the SAS Web Application Server. 1 In <SAS-configuration-directory>/Levn/Web/WebAppServer/

SASServer6_1/sas_webapps/sas.customerintelligencestudio.war/ config.xml, edit the session time-out value in the following code: <enabled>true <maxInactiveInterval>604800

2 In <SASConfigDir>/Levn/Web/WebAppServer/SASServer6_1/

sas_webapps/sas.customerintelligencestudio.war/WEB-INF/ web.xml, edit the following code: <session-config> <session-timeout>10080

<path>/

The time-out values in both files must be equivalent. Note: The settings for time-out values are overwritten when you apply a SAS Customer Intelligence hotfix and redeploy the SAS Customer Intelligence Studio web application.

Set an Event Time-Out in SAS Management Console When connected to online channels, the SAS Decision Services engine receives, processes, and responds to requests in real time. When defining an event in SAS Management Console, an is able to specify a timeout setting for the event. Specifying a time-out setting controls the maximum amount of time that SAS Decision Services spends processing a request of that event type before returning a time-out error. It is possible for the flow that is associated with the event to also have a time-out setting. If that is the case, the flow time-out setting overrides the event time-out setting. This capability ensures that a response is provided within a specified time that is appropriate for the channel and the type of customer interaction. The time-out setting for a call center interaction might need to be longer than the time-out setting for an automated teller machine (ATM). Setting the time-out ensures that a response (even if it is an error response) is returned to the channel within the time limit. If a request is not completed within the time-out interval, fault processing is initiated. Note: It is highly recommended that you set the time-out on the event, instead of in the Start node of a campaign, so that you can quickly change the time-out settings when necessary. If you change the time-out in the Start node of any campaign, the time-out will be embedded in your decision flow and you must


85

redeploy your entire campaign (and all linked objects) to override the settings in the production environment. Setting the time-out in the Start node can cause test cases with small time-out values (for example, the web channel) to fail. These test cases fail because the SAS Decision Services design server cannot execute the flows as quickly as the SAS Decision Services Engine server. Therefore, use the default event time-out on the design server when testing campaigns and use SAS Management Console to set the event time-out value on the engine server. Time-out values can be set at three levels (from lowest to highest): system, event, and flow. Event and flow time-out values are optional. n The system time-out value can be set during the installation and

configuration of the SAS Decision Services design server and engine. If no value is specified by the , then a default value is set. The value can be viewed in Configuration Manager in SAS Management Console. If you change the value through Configuration Manager, the new setting will not take effect until the system is restarted. Here are the property names for system time-out: o

Engine server: sasds.engine.execution.system.timeout.ms

o

Design server: sasds.designserver.test.system.timeout.ms

n Use the Decision Services Manager plug-in of SAS Management Console to

set the time-out value at the event level. n The flow time-out value supersedes the event and system time-out values.

Use the SAS Customer Intelligence Plug-in for SAS Management Console to set the time-out at the flow level. Note: Specify all time-out values in milliseconds. If a sub-flow is called, then the time-out value of the top-level flow or event is used. If the time-out values of the flow or the event are not specified, then the system time-out value is used. Set the event time-out value by using the Decision Services Manager plug-in for SAS Management Console. To set the time-out value for an event, follow these steps: 1 Launch SAS Management Console. 2 Expand the Decision Services Manager and SAS Decision Services

servers folders.

Expand the system that contains the event that you want to update. Expand the Events folder and the repository. 3

Right-click the event that you want to change, and select Set Timeout.

86 Chapter 3 / Setting Up the Environment

4

Select Enable to edit the time-out value, enter the value in milliseconds, and click OK. If Enable is cleared, then the time-out value for the event is disabled.

Prevent s from Adding Attachments You can prevent s from adding images and attachments to campaigns. To disable attachments, set the following property in the config.xml file that is in the root directory for the sas.customerintelligencestudio.war file. true

Attachments and images that were added previously to diagrams, the Attachments page, and the Properties page are still displayed. The Comments page does not display attachments that were added previously. s are not able to add any new attachments or images.

Enable Staging of Treatments You use the Stage node to stage treatments that can be used in multiple campaigns and on multiple channels. Staged treatments ensure that the right offer is delivered in the right channel at the right time. Global variables that affect the functionality of the staged treatment are created on the first use of the software. For more information, see “Predefined Global Variables” on page 63. Note: If you are working with staged treatments that were created in SAS Marketing Automation, set the time zone in SAS Real-Time Decision Manager to


87

Greenwich Mean Time (GMT) before you run the campaign. For information about setting the time zone for a campaign, see SAS Real-Time Decision Manager ’s Guide.

Set JVM Options In UNIX, you set JVM options in /Web/WebAppServer/ SASServer6_n/bin/setenv.sh. In Windows, you set JVM options in \Web\WebAppServer\SASServer6_n\conf\wrapper.conf.

You must edit the setenv.sh or wrapper.conf file for every server in a cluster. The recommended minimum JVM memory size is 4 GB for SASServer7 and 8 GB for SASServer6. If there are more than 200 campaigns and treatment campaigns, the recommended JVM memory size for SASServer7 is 8 GB. For more information, see “Tuning the JVM Memory Size” on page 301.

Lock Down a SAS Server You can limit the reach and activities of a SAS server by putting it in a lockeddown state. When running SAS in a locked-down state, access to files and directories on the host system is restricted to a lockdown path list (a specified list of paths and files that are valid for the SAS server to access). SAS Decision Services requires that the <SAS_Configuration_Directory>/ Applications/SASDecisionServicesServerConfig/DS2Conversion/ design directory be added to the lockdown path list by the SAS .

The location of the directory is configurable. However, the specific configured location can be found on the Advanced tab of the Decision Services Design Middle Tier Properties dialog box, as the value of the sasds.designserver.ds2.generation.folder.path property. Note: The scoring activity publishing will fail if the directory is not added to the lockdown path list. The directory is not added to the list by default. You can lock down at the SAS Application Server level as well as the Pooled Workspace Server level. By default, the Pooled Workspace Server is configured to run under SASApp, and the value is SASApp - Logical Pooled Workspace Server. The specific name of your Pooled Workspace Server can be found on the Advanced tab of the Decision Services Design Middle Tier Properties dialog box, as the value of the sasds.designserver.logical.workspace.server.name property. It is recommended that you lock down at the higher SAS Application Server level, which locks down all servers under SASApp (such as the Logical Pooled Workspace Server and the Logical Stored Process Server). Then, apply the lockdown path list at the specific Pooled Workspace Server level. This is the most restrictive option and does not allow other servers under SASApp to write to the accessible folders that are meant for the Pooled Workspace Server. The lockdown can be effected by modifying the sasv9_mods.cfg file (found at <sas-configuration-directory>/Lev1/SASApp/) by specifying the following option: -lockdown

To specify what folders the SAS server can write to, modify the autoexec_mods.sas file by creating (or adding the folder to) an entry in the following form:

88 Chapter 3 / Setting Up the Environment lockdown path= "<sas-configuration-directory>\Lev1\Applications\SASDecisionServicesServerConfig\ DS2Conversion\design";

For specific instructions on lockdown, and to create or append a list of folders that the SAS server can write to, see the SAS Intelligence Platform: Security istration Guide.

Monitoring You can use the SAS Decision Services Monitor to query activity hit counters and execution performance statistics. The Monitor also controls production batch execution, and provides access to batch job progress, status, and results. The SAS Decision Services Monitor collects performance statistics from SAS Decision Services engines, saves them in a database, and s querying this data. The following describes the implementation of the SAS Decision Services Monitor. SAS Decision Services engines expose the following statistics for monitoring: n Event counts — The number of times an event is executed. n Node counts — The number of times a particular node of a flow is executed. n Flow response time —The average response time of a flow in milliseconds.

The monitoring framework monitors the SAS Decision Services engine, or a cluster of engines, collects the information over a specified duration, and queries on the data. For information about configuring monitoring levels, see “SAS Decision Services Monitoring” on page 279

Set the Delimiter for Multiple Treatments The _SAS_CAMPAIGN_TREATMENT_SEPARATOR delimiter is used when a treatment-related variable (for example, a treatment code) in the Package directory is assigned to a string type variable (for example, a reply variable). In this case, if there are multiple treatments assigned to the package, the value (for example, TreatmentCode) from each treatment is concatenated together, separated by the separator, and assigned to the variable. Updates to the separator are made in the predefined global variable. When a new Design repository is created or when the predefined global variable is accidentally removed from the Design repository, the following -D option is used as the default value for the global variable. -Dcom.sas.analytics.crm.rtdm.delimiter = <delimiter>

Set the Size of Character Fields in Batch Simulation Tables When you append batch simulation output to an existing table, the default length for character fields is 500. You can change the size by entering an option in the following file on every SASServer6 node where SAS Real-Time Decision Manager is deployed. On Windows, the file is LevConfig\Web\WebAppServer \SASServer6_cluster_number\conf\wrapper.conf.


89

On UNIX, the file is LevConfig/Web/WebAppServer/ SASServer6_cluster_number/bin/setenv.sh. To change the length of character fields, enter the following option. -Dcom.sas.analytics.crm.inbound.batch_string_length=

Note: The maximum length that is ed by SAS data sets is 32767.

Import the Sample Definitions and Campaign A SAS package file that contains a sample campaign definition, reply definition, treatment, DS2 process, and campaign is installed with SAS Real-Time Decision Manager. The campaign contains some test cases that you can use to that your environment is configured correctly. You can import these objects into a business context where they are available to SAS Customer Intelligence Studio s. The package file is installed on the SAS server tier. To import the samples: 1 Copy rtdmsamples.spk from the SAS server tier to a location that is

accessible by SAS Management Console. On UNIX, the file is in the following location. <SASHome>/SASFoundation/9.4/misc/ma/Config/Deployment/Packages/rtdmsamples.spk

On Windows, the file is in the following location. <SASHome>\SASFoundation\9.4\ma\sasmisc\Config\Deployment\Packages\rtdmsamples.spk

SASHome is the directory where SAS is installed on your system. 2

Create a business context where s can access the sample campaign and definitions. For more information, see SAS Real-Time Decision Manager: ’s Guide.

3

Log on to SAS Management Console as a of the business context that you are importing the samples to. Note: Do not log on as an unrestricted .

4

On the Folders tab of SAS Management Console, right-click the folder that contains the business context and select Import SAS Package.

5 In the Import SAS Package wizard, select rtdmsamples.spk.

Do not select Include access controls. 6 Follow the rest of the steps in the wizard.

Managing Global Variables in SAS Management Console Note: For information about managing global variables in SAS Customer Intelligence Studio, see SAS Real-Time Decision Manager: ’s Guide. Global variables are values that are used to tune the behavior of flows at execution time. Unlike process variables that are specific to a flow, the value of a global variable affects the behavior of every flow that references it.

90 Chapter 3 / Setting Up the Environment For example, suppose a financial services institution wants to offer rates on short-term investment products when more than $10,000 is invested. A global variable called MinimumInvestment with an initial value of 10000.00 might be used in all flows that control the offers of short-term investments. Suppose it is later discovered that money is lost on such investment products when the investment is less than $12,000. Because a global variable was used, its value can easily be adjusted to 12000.00, rather than modifying every flow that controls the offering of a short-term investment. You must create global variables before creating the campaigns that use them. TIP If you are performance tuning, it can be helpful to minimize global

variables. To change the value of a global variable in the SAS Decision Services engine repository: 1

Launch SAS Management Console. Note: For security reasons, only an whose role includes the Set Global Value capability can change the value of a global variable. The values of the global variables in the SAS Decision Services design repository can be updated in SAS Customer Intelligence Studio.

2 On the Plug-ins tab, expand Decision Services Manager and the SAS

Decision Services servers folder.

3

Expand the system that contains the global variable that you want to update. Expand the repository, and select Global Variables.


91

4

Right-click the global variable that you want to change, and click Set Value.

5

Enter the new value and click OK. Use either single or double quotation marks to indicate a string value.

The new value is displayed in the table on the right pane.

The global variables in the design repository that are used for testing can be modified by using the Event category in the Definitions workspace in SAS Customer Intelligence Studio. For more information, see SAS Real-Time Decision Manager: ’s Guide.


Security istration Overview of Security istration The security model for SAS Customer Intelligence and the SAS Intelligence Platform provides the following features: n secure access to data and metadata n role-based access to application features n confidential transmission and storage of data n logging and auditing of security events n access control reporting

Security istration consists of the following tasks: n istering SAS identities for your s by adding information to

the SAS Metadata Server n istering groups of s in order to simplify the management of roles

and permissions n istering roles, which provide s with access to specific application

features n istering s’ permissions to access metadata repositories, folders,

and objects n istering s’ permissions in SAS Federation Server Manager to

control access to scoring models, custom DS2 code, and data access from DS2. Note: s, groups, and roles must all have unique names. For more information about security istration, see SAS Intelligence Platform: Security istration Guide at http://.sas.com/ documentation/onlinedoc/intellplatform/index.html and SAS Federation Server: 's Guide at http://.sas.com/documentation/onlinedoc/ fedserver/index.html.

How the LOCKDOWN Statement Affects Campaigns Overview of the LOCKDOWN Statement The LOCKDOWN statement secures a SAS Foundation server by restricting access from within a server process to the host operating environment. A SAS server in the locked-down state validates all access to the host file system through the lockdown path list. This list is often referred to as a whitelist. For more information, see SAS Intelligence Platform: Application Server istration Guide at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html.

Security istration

93

LOCKDOWN and External Treatment Lists On the Settings tab of the business context Properties window, you can select tables that are used in an external treatment list. If the tables were ed before the LOCKDOWN statement was issued, you can select the tables even if they are not on the whitelist. However, campaign treatments cannot reference the tables. If the table referenced by the external treatment list for a business context is not in the whitelist, then more treatments cannot be added to any campaigns. You can still run the campaigns, and will successfully use any treatments already associated with that campaign (because a copy of the treatment information is stored in the campaign when the treatment is first assigned).

istering SAS Identities for s Overview of SAS Identities For each , you must create an individual SAS identity on the SAS Metadata Server. The SAS identity is a copy of the ID with which the logs on to SAS applications. Based on this identity, the system can determine who can access which application, and can audit individual actions in the metadata layer. The SAS identity consists of a name and the ID for the ’s external . This ID can be any type of that is known to the metadata server’s host such as an LDAP, Active Directory, host, or other type of . When entering IDs for Windows s, be sure to qualify the ID (for example, WIN \myID or [email protected]).

Create SAS Identities To create SAS identities for your s, manually enter the information for each through the Manager plug-in in SAS Management Console. If you have a large number of s, then you can extract and group information from one or more enterprise identity sources. You can then use SAS bulk-load macros to create the identity metadata from the extracted information. For more information, see SAS Intelligence Platform: Security istration Guide at http://.sas.com/documentation/onlinedoc/intellplatform/ index.html.

The SAS Customer Intelligence Services ID A SAS Customer Intelligence Services ID is created during the installation and configuration of SAS Customer Intelligence. The ID has access to several system-level operations. The ID is automatically assigned to the correct roles and capabilities. If history is being updated by the CustIntelReporting middle-tier application, make sure that this ID has access permissions to the common data model database. For more information, see “Activate a History Process” on page 270. This ID must also have access to all business contexts. This ID is added by default to the Customer Intelligence access control template during installation. For more information, see “Using the Access Control Template (ACT)” on page 107.


istering Roles Overview of Roles In SAS Customer Intelligence applications, certain actions are available only to s or groups that have a particular role. A role is a set of capabilities that correspond to particular application features such as menu items and plug-ins. Any or group who is a member of a role has all of that role’s capabilities. Roles can contribute to one another. A role automatically includes all of the capabilities of a role that contributes to it. For example, the Customer Intelligence: Usage role contributes the Edit comments capability to the Customer Intelligence: istration role. Roles differ from permissions. In general, roles do not affect access to metadata or data.

View Roles in SAS Management Console To view information about roles: 1

Log on to SAS Management Console as an unrestricted .

2

Open the Manager plug-in in SAS Management Console.

3

Right-click a role, and select Properties. You can click the tabs to display the role’s , capabilities, and contributing roles.

Here is an example of the Capabilities tab for the initial configuration of the Customer Intelligence Common: role: Figure 3.1 Capabilities Tab for the Customer Intelligence Common: Role

Security istration

95

The following icons provide information about the capabilities: Table 3.2 Icon

Icons on the Capabilities Tab Description None of the capabilities in this category have been specified for this role. Some of the capabilities in this category have been specified for this role, either explicitly or through a contributing role. All of the capabilities in this category have been specified for this role, either explicitly or through a contributing role. To see details, click the plus sign (+).

Note: n Shaded check boxes indicate capabilities that come from contributing roles. n Some roles have implicit capabilities that are not specified on the

Capabilities tab. For more information, see “Predefined Roles for SAS Customer Intelligence” on page 95.

Predefined Roles for SAS Customer Intelligence Your installation includes several predefined roles for s and s of SAS Customer Intelligence. Depending on what software you have installed, you might have other predefined roles. Note: The ability to access and update campaign metadata is subject to permissions that are placed on that metadata. The SAS Customer Intelligence roles do not affect permissions. Here are the predefined roles: Customer Intelligence: Usage role This role provides the capability to log on to SAS Customer Intelligence applications. This role contributes to the other Customer Intelligence roles. The capability is implicit. It cannot be selected from the SAS Management Console. Customer Intelligence: Basic Campaign Design role In addition to the Customer Intelligence: Usage capabilities, s in this role have the implicit capability to access nodes with All s permission to design new campaigns. Node permissions are set in the Diagram Tools category of the Setup workspace in SAS Customer Intelligence Studio. Customer Intelligence: Advanced Campaign Design role In addition to the Customer Intelligence: Usage and the Customer Intelligence: Basic Campaign Design capabilities, s in this role can access nodes with Advanced s permission to design new campaigns, write code in Process nodes, and access operations and application resources features. For more information, Node permissions are set in the Diagram Tools category of the Setup workspace in SAS Customer Intelligence Studio.

96 Chapter 3 / Setting Up the Environment Customer Intelligence: istration role In addition to the Customer Intelligence: Usage capability, s in this role can manage decision campaigns, decision treatment campaigns, treatment campaign sets, diagram tools, information map metadata, channels, staged treatments, custom processes, and deployments. Customer Intelligence Common: role s in this role can access SAS Customer Intelligence Studio from the SAS Visual Analytics Home page and manage the categories in the istration workspace: business contexts, sessions, locks, and environment settings.

Capabilities of Predefined Roles for SAS Customer Intelligence The following table lists and describes the decision operations capabilities in each of the predefined roles. In the Manager plug-in, SAS Management Console displays the capabilities on the Capabilities tab in the Properties window for each predefined role. On the Capabilities tab, navigate to the Operations folder: Applications  Customer Intelligence Core 6.5  Decision  Operations. Table 3.3

Decision Operations Capabilities

Capability

Description

Allow mark campaign for deployment

enables the to mark a campaign ready for deployment.

Manage promotion

provides access to the promotion interface.

Allow manage remote deployment environments

enables the to manage remote deployments in the Deployments category on the istration page of SAS Customer Intelligence Studio. The must have Edit permission for the selected business context.

Allow deploy and undeploy campaigns

enables the to deploy and undeploy selected campaigns in the Deployments category on the istration page of SAS Customer Intelligence Studio.

Allow activate and deactivate campaigns

enables the to activate and deactivate campaigns in the Deployments category on the istration page of SAS Customer Intelligence Studio.

Allow repository maintenance

enables the to click Maintenance and remove repository objects from the Deployments category on the istration page of SAS Customer Intelligence Studio.

The following table lists and describes the decision application resources capabilities in each of the predefined roles. In the Manager plug-in, SAS Management Console displays the capabilities on the Capabilities tab in the

Security istration

97

Properties window for each predefined role. In the Capabilities tab, navigate to the Applications  Customer Intelligence Core 6.5  Decision  Application Resources folder. Table 3.4

Decision Application Resources Capabilities

Capability

Description

Manage decision campaigns

enables the to manage SAS RealTime Decision Manager campaigns.

Manage decision treatment campaigns

enables the to manage SAS RealTime Decision Manager decision treatment campaigns.

Manage decision campaign sets

enables the to manage SAS RealTime Decision Manager decision treatment campaign sets.

Manage decision treatment campaign definitions

enables the to manage SAS RealTime Decision Manager decision treatment campaign definitions.

Manage reply definitions

enables the to manage reply definitions.

Manage decision custom diagram tools

enables the to view, edit, and use SAS Real-Time Decision Manager custom diagram tools.

Manage identifiers

enables the to view, edit, and use identifiers.

Manage global variables

enables the to view, edit, and use global variables.

Manage decision data processes

enables the to manage data processes in SAS Real-Time Decision Manager.

Manage decision Web service processes

enables the to manage web service processes in SAS Real-Time Decision Manager.

Manage decision SAS processes

enables the to manage SAS processes in SAS Real-Time Decision Manager.

Manage models

enables the to view and use models.

Manage rules

enables the to view and use rules.

The following table lists and describes the decision nodes capabilities in each of the predefined roles. In the Manager plug-in, SAS Management Console displays the capabilities on the Capabilities tab in the Properties window for

98 Chapter 3 / Setting Up the Environment each predefined role. In the Capabilities tab, navigate to the Applications  Customer Intelligence Core 6.5  Nodes folder. Table 3.5

Decision Nodes Capabilities

Capability

Description

Allow use of advanced nodes

enables the to create and use nodes with Advanced permission.

Allow writing code in Process node

enables the to enter code in the Process node.

The following table lists and describes the decision application resources capabilities in each of the predefined roles. In the Manager plug-in, SAS Management Console displays the capabilities on the Capabilities tab in the Properties window for each predefined role. In the Capabilities tab, navigate to the Applications  Customer Intelligence Core 6.5  Applications Resources folder. Table 3.6

Decision Application Resources Capabilities

Capability

Description

Manage treatments

enables the to manage treatments.

Manage staged treatments

enables the to manage staged treatments.

Manage custom detail groups

enables the to manage custom detail groups.

Manage custom detail tags

enables the to manage custom detail tags.

Manage response definitions

enables the to view, edit, and use response definitions.

Manage built-in diagram tools

enables the to manage diagram tools that are supplied with the application.

Manage events

enables the to manage events.

The following table lists and describes the customer intelligence studio istration resources capabilities in each of the predefined roles. In the Manager plug-in, SAS Management Console displays the capabilities on the Capabilities tab in the Properties window for each predefined role. In the

Security istration

99

Capabilities tab, navigate to the Applications  Customer Intelligence Studio 6.5  istration Resources folder. Table 3.7

Customer Intelligence Studio istration Resources Capabilities

Capability

Description

Manage business contexts

enables the to view and use business contexts. Note: Edit capability is set in the properties for the business context. For more information, see “Managing Permissions for s and Groups” on page 144.

Manage sessions

enables the to manage sessions.

Manage locks

enables the to view and release locked objects such as campaigns.

Manage environment settings

enables the to manage environment variables.

The following table lists and describes the comments capabilities in each of the predefined roles. In the Manager plug-in, SAS Management Console displays the capabilities on the Capabilities tab in the Properties window for each predefined role. In the Capabilities tab, navigate to the Applications  SAS Application Infrastructure  Comments folder. Table 3.8

Comments Capabilities

Capability

Description

Delete comments

enables the to delete existing comments.

Edit comments

enables the to edit existing comments.

The following table lists and describes the reports capabilities in each of the predefined roles. These capabilities are located in SAS Management Console at the Applications  Cust Intel Report Mid-Tier  Application Resources node. Table 3.9

Reports Capabilities

Capability

Description

Manage reports

enables the to create, save, rename, and delete reports in the Reports workspace.

100 Chapter 3 / Setting Up the Environment Capability

Description

View reports

enables the to view reports in the Reports workspace.

In the following table, an asterisk (*) indicates that the capability is from a contributing role. Table 3.10

Predefined Roles and Assigned Capabilities

Customer Intelligence: Usage Role

Customer Intelligence: Basic Campaign Design Role

Customer Intelligence: Advanced Campaign Design Role

Customer Intelligence: istration Role

Customer Intelligence Common: Role

X

X*

X*

X*

X*

Manage decision campaigns

X

X

Manage decision treatment campaigns

X

X

Manage decision campaign sets

X

X

Capability Log on to Customer Intelligence Applications

Edit comments

X

X*

X*

X*

X*

Delete comments

X

X*

X*

X*

X*

View reports

X

Manage reports

X

Allow use of advanced nodes

X

Allow writing code in Process node

X

Allow mark campaign for deployment

X

Manage decision campaign definitions

X

Security istration

Capability




Manage decision treatment campaign definitions

X

Manage reply definitions

X

Manage decision custom diagram tools

X

Manage identifiers

X

Manage global variables

X

Manage decision data processes

X

Manage decision web service processes

X

Manage decision SAS processes

X

Manage treatments

X

Manage custom detail groups

X

Manage response definitions

X

Manage events

X

Manage built-in diagram tools

X


X

Manage channels

X

Manage information map metadata

X

Manage staged treatments

X

101



Capability





Manage custom processes

X

Manage promotion

X

Allow manage remote deployment environments

X

Allow deploy and undeploy campaigns

X

Allow activate and deactivate campaigns

X

Allow repository maintenance

X


Manage business contexts

X

Manage sessions

X

Manage locks

X

Manage environment settings

X

Creating New Roles The predefined roles might be sufficient for many sites. Other sites might need to make application features available to s on either a broader or more granular basis than the predefined roles allow. For example, you might want to enable a to manage treatments, but not perform other application management tasks. In this case, create a role that specifies only the Manage treatments capability. Other combinations of capabilities can be used to create a new role. You can use only the capabilities that already appear in Manager. You cannot create new capabilities. For detailed information about roles and how to create them, see SAS Intelligence Platform: Security istration Guide at http://.sas.com/ documentation/onlinedoc/intellplatform/index.html.

Security istration

103

Modifying Roles The Manager plug-in in SAS Management Console enables you to modify roles by selecting or deselecting different capabilities. CAUTION! No automated method can revert a role to its original set of capabilities. Instead of adjusting the capabilities of a predefined role, consider creating a new role. This advice is especially important if major changes are needed.

If you modify a role, then follow these best practices: n Do not rename the predefined roles. Renaming the predefined roles makes it

difficult for SAS Technical to help you resolve problems. n Back up the metadata server before modifying roles, and keep a record of

the changes that you make. When modifying a role, you can use only the capabilities that already appear in Manager. You cannot create new capabilities. For more information about roles and how to modify them, see SAS Intelligence Platform: Security istration Guide at http://.sas.com/ documentation/onlinedoc/intellplatform/index.html.

istering Groups Overview of Groups Groups enable you to give multiple s hip in a role or permissions to metadata, thus simplifying security istration. You can create as many groups as are needed in order to manage your installation. In order to manage istration resources such as business contexts, sessions, and environment settings, a must be a member of the Customer Intelligence Common group. Note: The interface displays only groups that are created with the Customer Intelligence Usage: Role. This section describes the groups that are provided in your initial installation.

SAS s Group This group includes everyone who can access the metadata server, either directly or through a trust relationship. If a is able to log on to a client application and has an individual SAS identity, the is assumed to be in this group. Because this group has implicit hip, you cannot explicitly add or remove s from this group.

Public Group This group includes everyone who can access the metadata server, either directly or through a trust relationship. If a is able to log on to a client application but does not have an individual SAS identity, the is assumed to be in the public group. Because this group has implicit hip, you cannot explicitly add or remove s from this group.


SAS s Group This is a standard group for metadata s. In a standard configuration, are granted broad access and istrative capabilities, but are not unrestricted.

Customer Intelligence Basic Campaign Designer Group In your initial installation, this group is a member of the Customer Intelligence: Basic Campaign Design role. You can add s to this group to give them access to basic campaign design functionality. If SAS Marketing Operations Management is installed at your site, the following groups are added to the Customer Intelligence Basic Campaign Designer group. These groups have the same capabilities as the Customer Intelligence Basic Campaign Designer group. n Marketing Operations Integration Analysts n Marketing Operations Integration Services

Customer Intelligence Advanced Campaign Designer Group In your initial installation, this group is a member of the Customer Intelligence: Advanced Campaign Design role. You can add s to this group in order to give them access to advanced campaign design functionality. If SAS Marketing Operations Management is installed at your site, the following groups are added to the Customer Intelligence Advanced Campaign Designer group. These groups have the same capabilities as the Customer Intelligence Advanced Campaign Designer group. n Marketing Operations Integration n Marketing Operations Integration Campaign Designer

Customer Intelligence Group In your initial installation, this group is a member of the Customer Intelligence: istration role. You can add s to this group in order to enable them to ister Customer Intelligence applications.

Customer Intelligence Common Group In your initial installation, this group is a member of the Customer Intelligence Common: role. You can add s to this group in order to enable them to manage istration resources such as business contexts, sessions, and environment settings.

SAS System Services Group This group enables to export files on the Folders tab of SAS Management Console.

SAS Decision Services Database s Group You must be a member of the SAS Decision Services Database s group to publish and execute SAS Decision Services DS2 code and to connect to a

Security istration

105

database through SAS Federation Server. For more information about this group, see SAS Customer Intelligence: Deployment Guide. The SAS Decision Services Database s group is a member of the Federation Server s group. For more information about the Federation Server s group, see “The and Federation Server s Group” in SAS Federation Server 4.2: ’s Guide. If SAS Decision Services was configured to connect to a third-party database, a shared will be defined on the s tab of the SAS Decision Services Database s Properties window. This shared will be used for connecting to the database through SAS Federation Server. For more information about shared s, see “Shared s” in SAS Federation Server 4.2: ’s Guide. A is also defined for General I/O database connections. The SAS Trusted and the SAS Federation Server System are added to the SAS Decision Services s group during configuration.

SAS Federation Server s Group This group grants the right to log on to the SAS Federation Server Manager web application and to istrate Federation Server Data Services and Data Service Names. For more information about this group and its role, see SAS Federation Server: ’s Guide. Note: Authentication errors occur in SAS Federation Server at for who were added to the SAS Federation Server s group through multiple group hips. To prevent the authentication errors, add s instead of groups to the SAS Federation Server s group.

istering Group and Role hip To ister group and role hip, log on to SAS Management Console as an unrestricted and use the Manager plug-in in SAS Management Console. In most cases, the best way to place a in a role is to add the to a group that belongs to the role. You can also add s directly to roles. To place a in one of the predefined roles, you can add the to one of the predefined groups: n To add a to the Customer Intelligence: Basic Campaign Design role, add

the to the Customer Intelligence Basic Campaign Designer group. The also receives the capabilities of the contributing role, Customer Intelligence: Usage. n To add a to the Customer Intelligence: Advanced Campaign Design

role, add the to the Customer Intelligence Advanced Campaign Designer group. The also gets the capabilities of the contributing roles, Customer Intelligence: Basic Campaign Design and Customer Intelligence: Usage. n To add a to the Customer Intelligence: istration role, add the

to the Customer Intelligence group. The also gets the capabilities of the contributing role, Customer Intelligence: Usage.

106 Chapter 3 / Setting Up the Environment Note: There is no reason to add a directly to the Customer Intelligence: Usage role. This role enables a to log on, and it can be used to filter lists of groups in other areas of the software. A can be added to more than one group, and a or group can be added to more than one role. For example, suppose a needs to perform both istration tasks and advanced application tasks. You could take one of the following actions: n Add the to both the Customer Intelligence group and the

Customer Intelligence Advanced Campaign Designer group. This method might be appropriate if only one needs this combination of capabilities. n Create a new group called Customer Intelligence: and

Advanced. You could then add the new group to both the Customer Intelligence: istration role and the Customer Intelligence: Advanced Campaign Design role. This method might be appropriate if multiple s need this combination of capabilities.

istering Permissions Permissions SAS provides a metadata-based authorization layer that supplements the protections from the host environment and other systems. Protections are cumulative across authorization layers. In order to perform a task, a must have sufficient access in all of the applicable layers. Although permissions can be assigned to individual s, it is recommended that you assign permissions for groups and then place s in those groups. Placing s in groups with previously assigned permissions decreases the work of maintaining your permissions structure and helps you avoid orphaned objects for which no s have permissions. You can set permissions at several levels: n Repository-level controls provide the default access controls for objects that

do not have other access controls. n Resource-level controls manage access to a specific item such as an

information map, a campaign, a node, a business context, or a folder. The controls can be defined individually by using explicit settings or in patterns by using access control templates. n Fine-grained controls affect access to subsets of data within a resource. You

can use these controls to specify who can access either particular rows within a table or within a cube dimension. The effect of a selected permission setting is influenced by any related settings that have higher precedence. For example, if a campaign inherits a permission from its parent folder but also has an explicit denial, then the explicit setting determines the outcome. Similarly, if a group has been granted a permission, and a who is a member of the group has an explicit denial, then the explicit setting determines the outcome. Most permissions are set by using the following methods: n The access control template (ACT), which provides a set of default

permissions.

Security istration

107

n Business contexts, which are groupings of campaigns. When you create a

business context, you specify which s can , and which s can view or edit the business context properties. Each of these methods is described in more detail below.

Using the Access Control Template (ACT) The Customer Intelligence access control template (ACT) provides a set of default permissions for SAS Real-Time Decision Manager resources. This template is automatically applied to all Customer Intelligence objects, including business contexts, campaigns, and nodes. In its initial configuration, this template denies Reetadata (RM) and WriteMetadata (WM) permission to the public group. You might want to update the ACT in these situations: n Give one or more s broad access to campaign data for the purpose of

application troubleshooting or istration. To do this, you can add the to the ACT, either permanently or temporarily, and specify the appropriate permissions. n Access campaign metadata that was created by a who is no longer in

your organization. To do this, temporarily add an to the ACT so that the can transfer the campaign permissions to a different . To update the ACT, open the Access Control Templates folder in the Authorization Manager plug-in in SAS Management Console.

Asg Permissions for Business Contexts Campaigns are grouped into -defined business contexts. Business contexts enable you to separate campaign depending on which s should have access. When you define a new business context, you specify which s can access the business context, and which s can view or edit the business context properties. Then, as campaigns are designed and created within the business context, the software applies access control entries (ACEs). ACEs give those s and groups the appropriate permission to access the campaign data and metadata. You must add s and groups to the appropriate roles before you can give them View or Edit permission for a business context. You can limit business context access to only groups by first using an istrative to create all of the business contexts for your site. When the istrative first creates a business context, that is added by default to the Permissions tab and to the s tab of the business context Properties window. The istrative can add groups to the Permissions and s tabs, and then remove the istrative ID from both tabs. CAUTION! s who are listed in the SAS Customer Intelligence ACT should not create business contexts. These s are excluded from the permissions list for business contexts. If they create business contexts, no other s have permission, and no s are listed on the permissions list.

New s and groups might not have immediate access to a business context. By default, the cache of permissions for a business context is refreshed every four hours. To modify the refresh interval, enter the following code in the /Web/WebAppServer/SASServer6_N/bin/setenv.sh file

108 Chapter 3 / Setting Up the Environment (UNIX) or the \Web\WebAppServer\SASServer6_N\bin \wrapper.conf file (Windows) of the web application server. -Dcom.sas.analytics.crm.bctx.cache.recache.minutes=number of minutes

Modifying Access Permissions for Promoting Objects Overview of Modifying Permissions In order to execute the promotion commands when using SAS Management Console to export and import objects to promote them, a must have permission to export objects from the source system and to import objects to the target system. You must also have permission to use the business context on the target system. To modify permissions, you must have istrative access to SAS Management Console. Using ACTs as described below is one way to ensure that a has access to the campaigns. To use the Deployment workspace in SAS Customer Intelligence Studio for promotion, the needs only View access to the campaigns that are being promoted, View access to the SAS Decision Services design repository on the source system, and Write access to the SAS Decision Services engine repository on the target system. For information about access permissions and promotion, see “Enabling a Single Identity” in SAS Customer Intelligence Deployment Guide.

Modify Access Control Templates on the Source and Target Systems Access permissions for business contexts and campaigns are set in the Customer Intelligence access control templates (ACTs). The Customer Intelligence Common Server Template controls access to business contexts. The Customer Intelligence Template controls access to campaigns. Both ACTs must be modified on the source and target systems. To modify the ACTs: 1

In SAS Management Console on the source system, open the Access Control Templates folder in the Authorization Manager plug-in.

Security istration

109

Figure 3.2 Access Control Templates

2

Right-click Customer Intelligence Common Server Template, and select Properties.

3

On the Permission Pattern tab of the Properties window, click Add to add a name.

4

Select the new name, and select the following permissions: n Reetadata n WriteMetadata n WriteMemberMetadata n ManageMemberMetadata n ManageCredentialsMetadata n CheckInMetadata n Read n Write

5 Click OK to save your changes. 6

Add a new to the Customer Intelligence Template properties, and select the following permissions for the new : n Reetadata n WriteMetadata n WriteMemberMetadata

7 Modify the same ACTs on the target system.

Modify Folder Permissions on the Target System The must be able to import objects into metadata folders on the target system. To set folder access permissions:

110 Chapter 3 / Setting Up the Environment 1

On the Folders tab of SAS Management Console on the target system, rightclick SAS Folders, and select Properties.

2

On the Authorization tab of the Properties window, click Add to add a name.

3

Select the new name, and select the following permissions: n Reetadata n WriteMetadata n CheckInMetadata

4

Click OK to save your changes.

Enable Integrated Windows Authentication in Firefox If you are using the Firefox browser in an environment that requires Integrated Windows Authentication, you must add your network to the Firefox configuration. This enables you to log on to SAS Customer Intelligence Studio. To add your network to the Firefox configuration: 1 In the Firefox browser address bar, type about:config.

A warning message is displayed. 2

Click the button to indicate agreement and display the configuration page.

3 On the configuration page, type network.automatic in the Search field. 4

Double-click network.automatic-ntlm-auth.trusted-uris.

5

Enter your site in the dialog box. Separate multiple sites with a comma. For example, you might enter multiple sites as http://sas.com, http://myintranetsite.com

6

Type network.negotiate in the Search field.

7

Double-click network.negotiate-auth.delegation-uris, and enter your network name in the dialog box. For example, you might enter a network name as cinetwork.com.

8

Double-click network.negotiate-auth.trusted-uris, and enter your network name in the dialog box.

For more information, see https://.mozilla.org/en-US/products/firefox.

Additional Configuration Required When Using Integrated Windows Authentication (IWA) or Web Authentication When you deploy SAS Real-Time Decision Manager or SAS Real-Time Decision Manager Run-Time Server and configure integrated windows authentication (IWA) or web authentication, the following additional tasks must be completed

Security istration

111

before the Design Repository JDBC connections to the SAS Federation Server using the com.sas.tkts.TKTSDriver driver are functional. 1

Log on to the SAS Management Console as the Unrestricted (sas).

2

In the Manager plug-in, create a new with Internal credentials.

3

On the s tab, click Create Internal .

4

Enter a and click OK.

5

On the Groups and Roles tab, add this new to the SAS Decision Services Database s group and the SAS Federation Server s group.

6

Click OK to save the new .

7

Open the SAS Decision Services Database group for editing.

8

Click the s tab.

9

Click New and add the sasfed@saspw credentials.

10 Click New to create a new Authentication Domain. 11 Enter SASDSFED_AUTH for the domain Name and check the Outbound

only check box. 12 Click OK to save the domain. 13 On the New Properties dialog box, select this new domain to associate

with the new . 14 Click OK to save the . 15 Click OK again to save the change to the SAS Decision Services Database

s group. 16 Click the Folders tab in the SAS Management Console and navigate to

System/Applications/SAS Decision Services/Decision Services 6.4/SASDSDesignRepository. 17 Right-click $SAS_Activity_Resource and select Edit System Resource on

the pop-up menu.

112 Chapter 3 / Setting Up the Environment 18 In the Edit System Resource “$SAS_Activity_Resource” dialog box, make

sure the Domain option is selected and select the SASDSFED_AUTH domain that you created in step 11. 19 Click OK to save the change and click OK when the Warning is displayed. 20 Make this change to any resource associated with a Design repository that

uses the com.sas.tkts.TKTS driver. These changes are not required for the SAS Decision Services Engine resources. 21 Restart SASServer7 and SASServer6 to activate the changes.

Updates Updates for SAS Customer Intelligence During SAS Customer Intelligence installation, the for the Customer Intelligence Services is updated when Update s is selected from SAS Deployment Manager. Note: s that are controlled by an external provider (such as in LDAP, Active Directory, or the host operating system) are not synchronized. Make sure that the s that you provide as input match the actual s in your external provider.

Updates for SAS Decision Services The following table summarizes details about the SAS Decision Services s that were updated by the SAS Deployment Manager and the s that must be updated manually. The path to the SAS Decision Services resources in the SAS Metadata Repository is SAS Folders\System\Applications\SAS Decision Services\Decision Services 6.4\ . There is usually a design repository folder and an engine repository folder. However, that might not always be the case. ID

Usage

Update Description

SAS Spawned Server

Used by activity publishing.

This is updated automatically when Update s is selected from SAS Deployment Manager.

Decision Services Web Infrastructure Platform Data Server

Used to store monitor, , and batch tables. Used in the SAS Decision Services system resource.

This is updated automatically in the SAS_Server_7 application server data source and the Web Infrastructure Platform Data Server when Update s is selected from the SAS Deployment Manager. Update $_Log_JDBCConnectionResource using SAS Management Console or the SAS Decision Services UpdateResource utility. For more information about the UpdateResource utility, see SAS Customer Intelligence: Deployment Guide.

Security istration

113

WS-Security Integration Overview WS-Security secures the message transmission between SAS Customer Intelligence and the SAS Decision Services engine. The use of WS-Security with SAS Decision Services is optional. Any of the three implemented aspects of WSSecurity can be used alone or can be specified in conjunction with any combination of the other aspects. The following aspects have been implemented: Timestamp The message is marked by the sender with creation and expiry timestamps, which the receiver validates. The SAS Decision Services web service can be configured to validate the request message with the expiry timestamp, as well as an offset from its own clock. It can also set timestamps on the reply message. This mechanism is used to prevent replay or "man-in-the-middle" attacks. Signature Message g is implemented by the sender g the message using its private key and the receiver decrypting it using the trusted or public key of the sender's key. This is true for both request and response messages. The server needs to access the trusted key of the client's private key, and the client needs access to the trusted key of the server's private key. Frequently, the public keys might have to be certified by a certificate authority. Encryption This is implemented by using a symmetric key that travels with the message. The key is encrypted by the sender, using the trusted key of the receiver (opposite of g). Like with the signature, this mechanism is true for both request and response messages. The sender can send only to a received whose trusted key is available to the sender. All s can also be sas002 encoded.

Implementation The SAS Decision Services web service is implemented as a Java web application. WS-Security is implemented using Apache WSS4J. The WSSecurity implementation can be configured and customized by setting the appropriate values for system properties. Not all features of Apache WSS4J are exposed or configurable. To configure some of the features, private and trusted keys are required. These keys are held in keystores. Sometimes it is convenient to hold the private and trusted keys in separate stores. A keystore holding only trusted keys is also known as a truststore. The JRE implementation contains a truststore called CACerts that is used by default. As part of setting up WS-Security, public and private keys must be created, certified by certificate authorities, and distributed among the client and server keystores, as per your IT policies.


Configuration The following system properties can be used to configure the WS-Security implementation in the SAS Decision Services engine web service: Note: All s can be sas002 encoded. Category

Description

Signature Key Store

The keystore containing the key used for g outgoing messages.

Signature Trust Store

Encrypt Key Store

Encrypt Trust Store

General

Property

Default Value Points to the CACert in JRE.

to access this keystore.

sasds.wssecurity.signatureKeyStor e.

changeit

Location of this keystore.

sasds.wssecurity.signatureKeyStor e.location

file:${java.home}/lib/ security/cacerts

The keystore containing trusted certificates for ing signed incoming messages.

Points to the CACert in the JRE .


sasds.wssecurity.signatureTrustSt ore.

changeit


sasds.wssecurity.signatureTrustSt ore.location


The keystore containing key used for decrypting incoming messages.

Points to the CACert in the JRE.


sasds.wssecurity.encryptKeyStore.

changeit


sasds.wssecurity.encryptKeyStore. location


The keystore containing the key used for encrypting outgoing messages.

Points to the CACert in the JRE.


sasds.wssecurity.encryptTrustStor e.

changeit


sasds.wssecurity.encryptTrustStor e.location


The general WS-Security properties.

Security istration Sets the name of the validation actor.

sasds.wssecurity.validationActor

Actors are subsystems that process the SOAP message with a specific purpose.

Timestamp

Signature

The actor name of the wsse:Security header. If this parameter is omitted, the actor name is not set. The value of the actor or role has to match the receiver's setting or can contain standard values.

sasds.wssecurity.securementActor

Enables the mustUnderstand attribute on WS-Security headers on outgoing messages.

sasds.wssecurity.securementMust Understand

True

Determines whether outbound timestamps have precision in milliseconds.

sasds.wssecurity.timestampPrecisi onInMilliseconds

True

Determines whether to enable strict timestamp handling. If this is true, then use the validationTimeToLive to determine whether a message is expired. Otherwise, use the expiry timestamp on the message.

sasds.wssecurity.timestampStrict

False

The time difference between creation and expiry time in seconds in the WS-Security timestamp of the outbound message.

sasds.wssecurity.securementTime ToLiveInSeconds

300

Determines whether to enable strict timestamp handling. If this is true, then use the validationTimeToLive to determine whether a message is expired. Otherwise, use the expiry timestamp on the message.

sasds.wssecurity.validationTimeTo LiveInSeconds

300

Whether to enable signature confirmation.

sasds.wssecurity.enableSignature Confirmation

False

The alias name of the private key used to sign the outbound message.

sasds.wssecurity.securement name

The properties used for timestamping the messages or for validating the timestamp on a message.

The properties that control validating the signature on an inbound message as well as creating a signature on an outbound message.

115

116 Chapter 3 / Setting Up the Environment The alias name of the private key used to sign the outbound message. If both this value and sasds.wssecurity.securementname are set, this value prevails.

sasds.wssecurity.securementSign ature

The of the private key used to sign the outbound message.

sasds.wssecurity.securement word

Describes how the key is referenced in a signed or encrypted message header. Valid values are:

sasds.wssecurity.securementSign atureKeyIdentifier

IssuerSerial

sasds.wssecurity.securementSign atureAlgorithm

The default is set by the data in the certificate.

sasds.wssecurity.securementSign atureParts

The SOAP body is signed by default.

sasds.wssecurity.validationEncrypt ionHandler

embeddedEncryptedSym metricKeyValidationHandl er

n IssuerSerial n DirectReference n X509KeyIdentifier n Thumbprint n SKIKeyIdentifier n KeyValue (signature only) n EncryptedKeySHA1 (encryption

only)

For certificate authentication use DirectReference. Defines what signature algorithm to use. The default is set by the data in the certificate, such as one of the following: n http://www.w3.org/2000/09/

xmldsig#rsa-sha1

n http://www.w3.org/2000/09/

xmldsig#dsa-sha1

Parameter to define what parts of the request should be signed.

Encrypt

The properties that control the decryption of inbound and outbound messages. Two values are possible: embeddedEncryptedSymmetricKeyV alidationHandler The symmetric key for encryption is included in the message received. embeddedKeyNameValidationHandl er Only the name of the key is available in the message. In both cases, use the next property to retrieve the private key for decrypting.

Security istration

117

The for the private key used to decrypt the inbound message.

sasds.wssecurity.validationEncrypt PrivateOrSymmetricKeyP assword

The name for encryption. The encryption function uses the public key of this 's certificate to encrypt the generated symmetric key. If only the encryption of the SOAP body data is requested, it is recommended to use this parameter to define the name.

sasds.wssecurity.securementEncr yption

The text of the key name to be sent for encryption in the KeyInfo.

sasds.wssecurity.securementEncr yptionEmbeddedKeyNam e

Defines what key identifier type to use. The WS-Security specifications recommends that you use the identifier type IssuerSerial. Possible values are:

sasds.wssecurity.securementEncr yptionKeyIdentifier

IssuerSerial

sasds.wssecurity.securementEncr yptionKeyTransportAlgori thm

http://www.w3.org/ 2001/04/xmlenc#rsaoaep-mgf1p

sasds.wssecurity.securementEncr yptionSymAlgorithm

http://www.w3.org/ 2001/04/xmlenc#aes128cbc

If this parameter is not set, then the encryption function falls back to the sasds.wssecurity.securement name property to get the certificate.

n IssuerSerial n X509KeyIdentifier n DirectReference n Thumbprint n SKIKeyIdentifier n EmbeddedKeyName

Defines what algorithm to use to encrypt the generated symmetric key. Currently Apache WSS4J s: n http://www.w3.org/ 2001/04/

xmlenc# rsa-1_5


xmlenc#rsa-oaep-mgf1p

Defines what symmetric encryption algorithm to use. Apache WSS4J s the following algorithms: n http://www.w3.org/2001/04/

xmlenc#tripledes-cbc


xmlenc#aes128-cbc


xmlenc#aes256-cbc


xmlenc#aes192-cbc

Except for http://www.w3.org/ 2001/04/xmlenc#aes192-cbc, all of these algorithms are required by the XML encryption specification.

118 Chapter 3 / Setting Up the Environment Property to define what parts of the request should be encrypted. For more information, refer to Apache WSS4J documentation. Actions

sasds.wssecurity.securementEncr yptionParts

If no list is specified, the handler encrypts the SOAP body in Content mode by default.

sasds.wssecurity.validationActions

NoSecurity

sasds.wssecurity.securementActio ns

NoSecurity

These are space-separated lists of tokens that define the steps for incoming (validation) or outgoing (securement) messages. The valid tokens SAS Decision Services s are NoSecurity, Timestamp, Signature, and Encrypt. The order in which these are applied is important and must match the sender’s or receiver’s order for validation and securement respectively.

These properties can be set by defining them in the SAS Management Console Configuration Manager plug-in for SAS Decision Services. In SAS Management Console, locate the properties for SAS Decision Services Engine under Application Management  Decision Services Engine Server 6.4. On the Advanced tab, add or update the properties that you need to set. For example, you could define a property with a name of sasds.wssecurity.securementEncryptionKeyIdentifier and a value of X509KeyIdentifier

Tools For most implementations, it is required to create keystores with private and public key pairs in them, and then distribute them in other keystores. KeyTool is a command-line utility distributed with a JRE. Here are some common commands that are useful when setting up keystores for WS-Security: keytool -genkeypair -alias -keyalg -sigalg <signature algorithm> -validity -key store Generates a private and public key pair in the keystore. It also creates a new keystore if it does not exist. keytool -list -v -key store Lists keys in the keystore. keytool -export -alias -key store -rfc -file Exports the public key from the keystore as a self signed certificate, for import into a truststore. keytool -certreq -alias -key store -file Generates a certificate request for sending to a certificate authority. keytool -import -alias -file -key store <trust store name> Imports the certificate into the truststore.

System Resources 119

System Resources Overview System resources enable decision flows to access and interact with resources such as SAS servers, database servers, or external web services. Activities reference the system resources by name. For example, many activities run a SAS DS2 program to produce results. The middle tier portion of these activities must communicate with a SAS Federation Server. A system resource type named JDBC Connection provides the information that is needed to facilitate such communications. More specifically, the JDBC Connection system resource contains information that is needed by a SAS activity to execute a DS2 program running on the SAS Federation Server. Also, a different JDBC Connection system resource is used to connect to database servers for use in a data process. When you are accessing database tables other than SAS data sets, these resources point directly to the database using the database’s native JDBC driver. The web service system resource is often used to connect to external web services. By providing the end point URL, SAS Decision Services can use the web service that is pointed to. The HTTP system resource is used for exchanging information between SAS Decision Services and SAS 360 Discover. Activities use a name to reference system resources instead of containing the resource information directly. Thus, flows are portable between systems. The product s configurable design, test, and production environments. Typically, the sets of back-end SAS servers that are used by development, test, and production environments are different. System resources enable the correct set of servers to be used in each environment without modification of flows or activities. That is, each environment contains system resources that have the same names. However, the information that is contained by these system resources differs from environment to environment.

Standard System Resources When your system was initially installed and configured, several system resources were created by default.

$SAS_Activity_Resource Configured to reference a SAS Federation Server for the purpose of executing SAS activities. SAS activity code is contained in DS2 packages. By default, these DS2 packages are stored in SAS data sets. It is possible to reconfigure the system to store activity DS2 packages in a third-party database, if you so choose. your SAS on-site personnel for assistance. Note: Scoring models and business rules are published as SAS activities. For more information, see SAS Federation Server: ’s Guide.


GeneralIO_Activity_Resource Configured to reference a third-party database management system for the purpose of storing and accessing data. By default, this system resource is configured to reference the database that was chosen during configuration. Also, by default, the General I/O activity is configured to use this system resource.

$_Log_JDBCConnectionResource Configured to reference a third-party database management system for the purpose of logging performance data. For more information, see “Data Collection for Performance Analysis” on page 283. By default, this system resource is configured to reference the third-party database that was chosen during configuration.

JDBC Connection System Resources About JDBC Connection System Resources JDBC Connection system resources are used by both SAS activities that execute DS2 programs and by data processes that access database records. The basic fields are listed in step 5 of the following section on page 121. In the case of a data process, the Connection Options value is not required. For data processes, multiple database server URLs can be specified, in a single system resource, in order to database clusters that do not have server-side load balancing. Each space-separated URL references one node of a clustered database environment. To connect to SAS data sets and to execute DS2 SAS activities, a JDBC Connection system resource must be configured to connect to one or more SAS Federation Servers. The JDBC Connection system resource named $SAS_ACTIVITY_RESOURCE is configured for this purpose. Advanced options are available that allow for the fine tuning of the connection and statement pools used by SAS Decision Services. These values should be set to appropriate values based on the hardware being used. A list of these options appears in “Tuning Controls” on page 286. To allocate computing resources efficiently, set up more than one SAS Federation Server in the server tier. Every server within a given cluster processes the same activity set. The following example illustrates this concept. Each middle-tier engine server can be configured to load balance every SAS Federation Server. Such a configuration guarantees that a middle-tier server failure does not block any SAS Federation Server from receiving and processing transactions. SAS Federation Server URLs are listed, space delimited, in $SAS_Activity_Resource. If a SAS Federation Server fails, an asynchronous thread periodically tests to see whether the server has come back online. If the server has come back online, the engine automatically re-creates an associated connection pool and brings the SAS Federation Server back into the cluster. This architecture makes the full processing capacity of the server cluster available to all processes. It also maximizes the retention of processing capacity in the event of a server failure. However, this configuration also requires calls to be made across machine boundaries. To improve performance, it is a best practice to restrict SAS Federation Server access to only local SAS Federation Servers co-located with the engine JVM. Load-balancer requests to a local SAS Federation Server are faster than


requests to a SAS Federation Server over the network. Requests to a local SAS Federation Server balances the load distribution more evenly between the instances of the SAS Federation Servers because the internal load balancing does not consider the load of servers. Load balancing across all SAS Federation Server instances over the network can cause an uneven load on the servers. It is also recommended to run at least two instances of SAS Federation Server instances that are co-located with the engine JVM for the following reasons: n The external load balancer for the engine JVMs might send requests to an

engine with a failed SAS Federation Server unless it monitors the status of the SAS Federation Servers by default. If there at least two instances of SAS Federation Server, requests can be successfully sent to an engine with a working SAS Federation Server instance even when another instance is failing. n A SAS Federation Server instance can handle only a finite number of

connections. If performance tuning requires a very large connection pool for the SAS Federation Server, one instance of SAS Federation Server might be insufficient. When there are high parallel connection rates, a single instance of SAS Federation Server will consume all available memory and crash. Alternatively, each middle-tier engine can be co-located with one SAS Federation Server. This deployment choice has the advantage of reducing calls across a network. It also simplifies the process of scaling up by adding servers, in that it does not require the analysis of middle-tier versus server-tier workloads. The following types use the JDBC Connection system resource: n SAS Activity n Data Process

JDBC for Enhanced Encryption for System Resources JDBC system resources for SAS Decision Services hold the name and information used to connect to the database server or the SAS Federation Server. By default, this is encoded using the sas002 encoding and held in the resource definition. However, some deployments might require stronger standards of encryption, as well as a centralized location to store the name and . It is possible for system resources to use information that is defined in the SAS Metadata Repository as credentials to connect to the database or the SAS Federation Server. Every or group that is defined in the SAS Metadata Repository can hold several s, each containing an authentication domain name, a ID, and a corresponding . It is possible to configure the SAS Metadata Server to store these s, encrypted using the AES (SAS003) and AES/ FIPS (SAS004) algorithm. Note: The instructions for configuring the SAS Metadata Server are described in SAS Intelligence Platform: System istration Guide. You must have SAS/SECURE installed to AES or AES/FIPS encryption. Both the SAS Decision Services Engine server and the design server use system resources to connect to databases or the SAS Federation Server. The SAS Decision Services Engine uses the SAS Trusted identity to access secure data. The design server uses the identity of the actual caller to do the same.

122 Chapter 3 / Setting Up the Environment The value in the name entry in the system resource is used to determine the credentials to connect to the server. The system first attempts to match the value with a SAS Server definition in the SAS Metadata Repository. The following scenarios are dependent on whether a match is found: n If there is a match, the authentication domain that is associated with the

server is used to select the information that is available to the . The information is used to connect to the server that is referenced by the system resource. The entry in the system resource is ignored. n If the name does not match any server name, the system searches the

available options of the for one that has an authentication domain that matches the name entry. The first such information to match is used to connect to the server that is referenced by the system resource. The entry in the system resource is ignored. If no match is found, the system reverts to using the name and the to connect to the server. Note: If a match is found, the system uses the credentials that are associated with the first match. If the credentials are incorrect or invalid, the system does not try to use other possible matches. It is recommended that you create a group and assign all s who need access to the resource to it. The information for the appropriate domain should be created for the group and not individual s. Separate groups can be created for the SAS Federation Server, databases, engine server usage, design server usage, and others, as required. Here is an example of using the enhanced encryption: 1 Create an authentication domain called FedServerDomain. Assign it to the

connection of the server using the Server Manager plug-in in SAS Management Console. 2

Create information for the group SASDSFedServers, for the FedServerDomain authentication domain, with the appropriate ID and that are needed to connect to the SAS Federation Server. Assign the SAS Trusted , the SAS , and other appropriate s to this group.

3 From the Folder tab, navigate to System  Applications  SAS Decision Services  Decision Services 6.4, select the repository, and edit the

$SAS_Activity_Resource system resource. Under Connection Credential Options, select one of the available options: Note: If you have not migrated to the first maintenance release of SAS Decision Services 6.4, Name/ is the only available option. Name/ Change the value in the Name field to Federation Server servername Lev1. Clear the field. Domain Select the domain from the drop-down menu. Server Select the SAS Federation Server from the drop-down menu. 4

Restart the SAS Decision Services web applications. that the SAS Decision Services Engine and design servers can connect to the SAS Federation Server by viewing the diagnostics page.


Use the same process to encrypt s for other JDBC connection resources that are connecting to other services. If your database server is not defined in the SAS Metadata Repository, you can create the domain when asg it to the group, and enter the name of the domain in the Name field of the system resource.

Specify a New System Resource as a JDBC Connection Note: If there are multiple JDBC driver JAR files in SASServer7_X/lib, delete every file except the one that you plan to use. The existence of more than one JDBC driver JAR file for each database might cause the execution of your campaign to fail. This problem occurs when a JDBC driver package for a specific database contains multiple JAR files. In this instance, all of the JAR files supply the same class name and the JAR file that is loaded first is used. This JAR file might be for the wrong database version or for the wrong Java version. You can use multiple drivers only if the classes do not clash and you are connecting to different databases. To create a new system resource as a JDBC Connection, click the Folders tab, and follow these steps: 1 Expand System  Applications  SAS Decision Services  Decision

Services 6.4. 2

Right-click a repository folder such as SASDSDesignRepository.

3 Select New System Resource from the drop-down menu. 4

Select JDBC Connection.

5

Complete any required fields in the dialog box that appears.

The and definitions that follow are also listed in the Help for this dialog box. Name specifies the name of the system resource. It has a 60-character maximum length. Spaces are allowed. Description (optional) might include the SAS activity or server cluster for which you plan to use this SAS connection. Description has a 200-character maximum length. Driver Class specifies the Java class name of the database or SAS Federation Server driver. To create a resource for accessing database tables, use the class name of the driver that is provided by your database vendor. If you are unsure of what driver class name to use, see your system . Table 3.11

ed Drivers for the Driver Class Field

Database

Class Name

DB2

com.ibm.db2.jcc.DB2Driver

Greenplum

org.postgresql.Driver

124 Chapter 3 / Setting Up the Environment Database

Class Name

Netezza

org.netezza.Driver

Oracle

oracle.jdbc.driver.OracleDriver

PostgreSQL


SAS Data Sets

com.sas.tkts.TKTSDriver

SQL Server

com.microsoft.sqlserver.jdbc.SQLServer Driver

Teradata

com.teradata.jdbc.TeraDriver

Server URL is a database URL of the form jdbc:subprotocol:subname. See your system for the URL that references your database installation. To create a system resource for executing DS2 activities, use the URL form jdbc:sastkts://host:port, where host and port reference your SAS Federation Server installation. If this system resource is used for executing SAS activities, and if you have more than one SAS Federation Server in your environment (recommended), then place the host’s file alias on each SAS Federation Server instance and then enter the alias in this field. For more information, see “Best Practices for SAS Decision Services Performance and High Availability” on page 24. Table 3.12

Examples for the Server URL Field

Database

URL*

Oracle

jdbc:oracle:thin:@//<server>:1521/ For example: jdbc:oracle:thin:@// machine1.unx.sas.com:1521/sasds

SQL Server

jdbc:sqlserver://[machine1.na.sas.com]

Teradata

jdbc:teradata://machine1/

DB2

jdbc:db2://<server>:5000/ For example: jdbc:db2:// machine1.na.sas.com:50000/sasds

Greenplum

jdbc:postgresql://<server>:5432/ For example: jdbc:postgresql:// machine1.unx.sas.com:5432/sasds

Netezza

jdbc:postgresql://<server>:5480/ For example: jdbc:netezza:// machine1.unx.sas.com:5480/SASDS

System Resources 125 Database

URL*

PostgreSQL

jdbc:postgresql://<server>:5432/ For example: jdbc:postgresql:// machine1.na.sas.com:5432/SASDS

* You must use a backslash (“\”) as an escape character when you use special characters in

the URL. For example, if you want to use a URL such as jdbc:sqlserver// [machine1.na.sas.com]\instancename, where “\” is a special character, you must enter jdbc:sqlserver//[machine1.na.sas.com]\\instancename.

Connection Options (optional) use this field to create a resource for executing DS2 activities. The connection options should be in the form of DRIVER=TSSQL;CONOPTS=(DSN=FederationServerDSN). For direct-to-database connections, see the documentation for the specific database, to determine what options are available. With direct-to-database connections, the connection options are optional. Name (optional) is used to connect to the database or SAS Federation Server that is specified in Server URL. (optional) is the that is used to connect to the database or to the SAS Federation Server that is specified in Server URL, along with the name. Domain (optional) is used to connect to the database or SAS Federation Server that is specified in Server URL. Note: The defined Domain can be added to the s tab for the SAS Decision Services Database s group so that all of the group can access the database or SAS Federation Server. Server (optional) is used to connect to the database or SAS Federation Server that is specified in Server URL. (optional) Click Advanced to access connection and statement pool tuning controls. For more information, see “JDBC Performance Tuning” on page 286.

Specify a New System Resource as a Web Service Connection The web service activity type is used to make direct requests to a web service as specified by the Web Service Connection system resource. To specify a Web Service Connection as a system resource, follow steps 1–3 in “Specify a New System Resource as a JDBC Connection” on page 123, and continue with these steps: 1 Select Web Service. 2


126 Chapter 3 / Setting Up the Environment The and definitions that follow are also listed in the Help for this dialog box. Name specifies the name of the system resource. Name has a 60-character maximum length; spaces are allowed. Description (optional) might specify the web service activity that you plan to use this system resource for. Description has a 200-character maximum length. WSDL URL (required) specifies the URL of the target web service. If the WSDL URL begins with https, then the Name and fields are also required. Note: You must enter a valid URL for the WSDL. If the URL contains spaces and other disallowed characters, they must be encoded. Host (optional) specifies the proxy server that forwards client requests to other servers. See your system for whether your installation uses a proxy server, and if so, what host name you should use. Port (optional) specifies the port that is used by the proxy server. Name If the WSDL URL begins with https (indicating that security is enabled), then this field specifies your name. If the WSDL URL begins with https (indicating that security is enabled), this field specifies your . After you click OK, the new Web Service Connection system resource should appear in the repository.

Specify a New System Resource as an HTTP Connection You must specify the HTTP connection resource that the SAS Decision Services Engine uses to communicate with servers that use HTTP (or HTTPS) as the transport protocol. The server capabilities are surfaced by specific activities that use this resource. The Name and URI fields are required. To specify an HTTP Connection as a system resource, follow steps 1–3 in “Specify a New System Resource as a JDBC Connection” on page 123, and continue with these steps: 1

Select HTTP Connection.

2


The and definitions that follow are also listed in the Help for this dialog box. Name specifies the name of the system resource. The name must be unique among the system resources.

Library Resources

127

Description specifies additional information about the system resource. Description has a 200-character maximum length. URI a URI that follows the HTTP or HTTPS scheme. The URI references the server that this resource communicates with. To configure the properties that are associated with this system resource click Advanced.

Library Resources Overview Library resources provide two distinct capabilities: n To define alias names for database schemas n To specify tables to cache in read-only memory

Note: Both of these features are optional and can be used together or separately.

Define a Schema Alias SAS Decision Services s the use of aliases to reference database schemas. For example, suppose your database has a schema called DDA, for directdeposit s, and the SAS programs in your organization reference this schema by using a libref called S. SAS Decision Services accesses data from your database directly, without going through SAS/ACCESS. Therefore, internally the SAS Decision Services Engine must use the actual schema name to access the tables within the schema. The name of the library system resource must match the name of the library (not libref) in SAS so that you can use that library for a data process in SAS Customer Intelligence Studio. For consistency with SAS, or to define -friendly names, you might want to create an alias for DDA called S by using a library resource. Your SAS Decision Services repository can contain zero or more library resources. You must create a library resource for each schema alias that you want to define. To specify a library resource, follow steps 1–3 in “Specify a New System Resource as a JDBC Connection” on page 123, and continue with these steps: 1 Select Library. 2

Complete any required fields in the dialog box that appears. The and definitions that follow are also listed in the Help for this dialog box. Name specifies the name of the library resource and the alias name to use. Host has a 60-character maximum length. Spaces are allowed.

128 Chapter 3 / Setting Up the Environment Description (optional) might describe the schema referenced by this library resource. Description has a 200-character maximum length. Schema Name the actual schema name defined to the database. Description has a 200character maximum length. Connection Resource select the JDBC Connection system resource from the drop-down list, which references the database with the desired schema.

Managing Databases Overview SAS Web Infrastructure Platform Data Server is included in your deployment for use as transactional storage by SAS Decision Services software. The server is based on PostgreSQL 9.x. The server is configured specifically to SAS. In a SAS Decision Services deployment, the server is configured to manage the DecisionServices database. This database contains and audit logs, and batch job execution and monitoring data that is generated by SAS Decision Services Monitor.

Connection Information for the JDBC Data Source The database that is used by SAS Decision Services must be configured in SAS Web Application Server as a JDBC data source. The JDBC data source is configured with the JDBC driver and connection information for the selected database. These settings are provided to the SAS Deployment Wizard during installation and configuration. The default database server for SAS Decision Services is the SAS Web Infrastructure Platform Data Server. The JDBC connection parameters for the server are provided in the following table: Table 3.13 Server

JDBC Connection Parameters for SAS Web Infrastructure Platform Data

Connection Parameter

Setting

JNDI name:

sas/jdbc/DecisionServices

JDBC URL:

jdbc:postgresl://serverName:port/ DecisionServices In the URL, substitute the server name and port number of the SAS Web Infrastructure Platform Data Server at your site. The default port is 9432.

JDBC driver class:


Managing Databases

129

These settings are configured during initial deployment. However, note the connection information so that you can supply it if you make changes later, such as moving the server to another host system. Note: You must specify the name and values as required to access the data source. For more information, see “Create a Database Shared and Domain for the JDBC Connection Resource” on page 142. These settings are represented in SAS Web Application Server in the SASconfig-dir\Levn \Web\WebAppServer\SASServer7_1\conf\server.xml file:

The postgresql.jar JAR file provides the org.postgresql.Driver class. SAS provides the JAR file in the SASHOME \SASWebInfrastructureDataBaseJDBCDrivers\9.4\Driver directory.

Database Requirements For information about database requirements, see SAS Federation Server: ’s Guide.

Configuring Additional Databases Overview During installation, standard SAS Decision Services deployments are configured for access to one third-party database management system and for access to SAS data sets. (Optional) Access to additional third-party database management systems can be configured. Note: These instructions assume that the additional database is to be used for data storage and access only, and not for use by SAS Federation Server to read DS2 packages. Note: It is possible to access databases through a SAS Federation Server. However, doing so results in degraded performance. Instead, configure SAS Decision Services to use the native JDBC driver provided by your database vendor. Your installation might include one or more development, test, or production environments. Repeat the procedures described in this section for each environment that you want to add the additional database to.

Database Installation Checklist Complete the following checklist. This information is used in see “Install Database Client and Server Software” on page 130.

130 Chapter 3 / Setting Up the Environment Table 3.14

SAS Decision Services Checklist — Database Information Defaults

Database Type:

Choose One: __DB2 9.5 or later __MS SQL 2008 or later Netezza 7.0 or later __Oracle 10g or later _PostgreSQL 9.1.3 or later __Teradata 12.0 or later

Database Host: Database Port: Database Name: Database ID: Database :

Install Database Client and Server Software SAS Decision Services uses Apache DB for its JDBC Connection and statement pooling implementation. Therefore, the connection pooling services of the J2EE application server are not used. The goal of installing the database client software is to make the native JDBC driver class for your database accessible to SAS Decision Services. For SAS Web Application Server, you must copy the JDBC driver JAR files to the application server's lib directory. To install the database client and server software: 1

Install the required database management system server software on a designated database server machine, and then configure your database server. See the installation documentation for the specific database.

2 Copy the JDBC driver JAR files to the /Web/WebAppServer/

SASServer7_N/lib directory in UNIX or to the \Web \WebAppServer\SASServer7_N\lib directory in Windows.

Note: You must copy only one JDBC driver JAR file for each database to the library.

Define Database s In the database schema, define a database ID with create, alter, and delete table permissions that is used to access data from the database and is also used as the Java Access ID.

Managing Databases

131

Define a JDBC Connection System Resource For more information, see “Specify a New System Resource as a JDBC Connection” on page 123.

Create Schema Aliases For more information about creating schema aliases, see “Define a Schema Alias” on page 127.

Changing the Database Selection Overview To change the database selection for SAS Decision Services, you must install the required database management system client software on each SAS Federation Server and the SAS Server. For more information, see the installation documentation for the specific database.

Oracle Add an entry into your TNSNAMES.ORA file and change the values that are shown in brackets to suit your environment. SAS uses addressname to connect to the database. SAS Federation Server and the JDBC connection system resources use sid to connect to the database. When defining this entry, define the addressname and the sid as the same value. = (DESCRIPTION= (ADDRESS_LIST= (ADDRESS= (PROTOCOL=T) (Host= ) (Port=<port>))) (CONNECT_DATA= (SERVICE_NAME=<sid>) ))

SQL Server and DB2 If you want to run the automated configuration of the log tables, create the ODBC data source names on the SAS Federation Server and the SAS Server, before you run the SAS Deployment Wizard configuration. After that, create the ODBC data source name as an istrative , and use the native database driver. The steps for creating these data source names vary depending on the operating system. To create data source names in Windows: 1

From the Start menu, navigate to Control  istrative Tools  Data Sources (ODBC).

2

On the System DSN tab, click Add.

3 Select the driver that corresponds to your database, and click Finish. 4

Complete the options below based on database type.

132 Chapter 3 / Setting Up the Environment SQL Server Data Source Name Enter the data source name. Description This is optional. Server Enter host for the SQL server database. With SQLServer Authentication Enter ID and . You can change default database This is optional You can change the log location This is optional. Select Test Data Source Select the data source. DB2 Data Source Name Enter the data source name. Description This is optional. Database Alias Select ADD. Data Source tab Enter the ID and . T/IP tab Enter the information for each field. 5

Test the connection on each DSN, and click Finish.

In UNIX or Linux, use the interactive ODBC Configuration Tool, dfdbconf, to add new data sources to the ODBC configuration. 1

From the root directory of the SAS Federation Server installation, run: ./bin/dfdbconf

2 Select A to add a data source. You can also use dfdbconf to delete a data

source. 3 Select a template for the new data source by choosing a number from the list

of available drivers. 4 You are prompted to set the appropriate parameters for that driver. The new

data source is then added to your odbc.ini file. After you have added all of your data sources, the interactive ODBC Viewer application, dfdbview, can be used to test your connection, as shown in the following example: ./bin/dfdbview my_odbcdsn

For non-ODBC connections, use the vendor-supplied client configuration utility. You might be prompted for a name and . If the connection succeeds, you will see a prompt from which you can enter SQL commands and

Managing Databases

133

query the database. If the connection fails, SAS Federation Server displays error messages describing the reasons for the failure.

General Steps To complete the database selection change after you have completed the database-specific steps: 1

Re-create the batch, monitoring, and log tables in the new database. The scripts for each table are located in the install directory of the SAS Decision Services server configuration. The path is Program Files \SASHome\SASDecisionServicesServerConfiguration \6.4\Configurable.

2 Copy the new JDBC JAR files into the SASServer7_N application server lib

directory. 3 In metadata, create an outbound-only domain (for example,

ORACLE_DOMAIN) and an outbound-only and Trusted-only domain (for example, ORACLE_DOMAIN@SASDS). 4

In SAS Federation Server Manager, log on as sasfed@saspw and then create a new Data Service Name (DSN) for your database using the authentication domain.

5 Enable Shared for the SAS Decision Services Database s group

on the generated DSN. 6 From the Decision Services Manager plug-in for SAS Management Console,

edit a system resource to point to the new database DSN.

Configure Access to SAS Data Sets To access SAS data sets from SAS Decision Services, create a system resource that references the SAS Federation Server that you intend to use for data set I/O, and then create a General I/O instance that references it. Note: You can also accomplish this by creating a data process through the Customer Intelligence plug-in for SAS Management Console. Note: If you did not configure a database connection for General IO in the SAS Deployment Wizard, $GeneralIO_Activity_Resource is set to SAS data sets by default. Except under special circumstances, SAS data sets should be used only for reading data. It is possible to create decision services that write SAS data sets, but in general this practice should be avoided. SAS Decision Services is multithreaded, and capable of executing multiple Read or Write operations concurrently. SAS data sets have file-level locking, so attempts to write data sets from multiple concurrent threads results in deadlocks and possibly loss of data. If you must write to SAS data sets, then set the connection pool values of both MaxActive and MaxIdle to 1 in the appropriate system resource. This causes I/O operations to be serialized but to perform slowly. If you must write data, the use of one of the ed database management systems is highly recommended.


Moving DS2 Persistence to a Database Management System To publish DS2 packages to a database management system instead of to SAS data sets: 1

Re-create the batch, monitoring, and log tables in the new database. The scripts for each table are located in the install directory of the SAS Decision Services server configuration. The path is Program Files \SASHome\SASDecisionServicesServerConfiguration \6.4\Configurable.

2

Copy the new JDBC JAR files into the SASServer7_N application server lib directory.

3

In metadata, create an outbound-only domain (for example, ORACLE_DOMAIN) and an outbound-only and Trusted-only domain (for example, ORACLE_DOMAIN@SASDS).

4

In SAS Federation Server Manager, log on as sasfed@saspw and then create a new Data Service Name (DSN) for your database using the authentication domain.

5 Enable Shared for the SAS Decision Services Database s group

on the generated DSN. 6

From the Decision Services Manager plug-in for SAS Management Console, edit the $SAS_Activity_Resource system resource to point to the new database DSN.

7 Use SAS Federation Server Manager to create a database DSN and

DataService, if you do not have one. Make sure you have installed the database management system client on SAS Federation Server. You can also modify the following SAS script to create the DSNs and DataService. Each database management system SAS program is located in the installation directory found in Program Files\SASHome \SASDecisionServicesServerConfiguration\6.4\Configurable \Utilities. PROC FEDSQL server=&server protocol=bridge port=&fedport uid="&authuid" pwd="&authpw" conn="(DRIVER=SYSCAT)"; CREATE DATA SERVICE &dataservice TYPE ORACLE CATALOG &catalog DOMAIN &domain {OPTIONS ( CONOPTS ( DRIVER ORACLE, PATH &path) ) }; CREATE DSN &feddsn under &dataservice NOPROMPT 'DRIVER=ORACLE' AS ; QUIT;

8

Add the new database DSN as the default DSN, by making it the first DSN on the list. To do this, remove BASE_DSN, and add the new database DSN. Then, add the BASE_DSN back again.

9 Modify the connection lib of the tap packages that are in the

loadutilpackages.sas program to point to the new database DSN.

Managing Databases

135

proc ds2 nolibs noprompt="driver=remts;server= ;port=21032; protocol=bridge;uid=<system>;pwd=<>; conopts=(driver=ds2;conopts=(driver=sql;conopts=(DSN=DATABASE_DSN)))";

10 In SAS Customer Intelligence Studio, test a publish of the DS2 code and

that a connection to the database occurs.

Manually Configuring SAS Decision Services Monitor and Log Tables on Alternate Databases The SAS Decision Services database includes tables to manage logs, and batch and monitor application data. However, if you decide to change databases, you must manually configure SAS Decision Services to use those tables. To do this: 1 Stop the application server where the SAS Decision Services monitor is

located (such as SASServer7_1). 2

Locate the file <SAS-configuration-directory>/Lev1/Web/ WebAppServer/SASServer7_1/conf/server.xml.

3 Configure your database. This process differs depending on the database

that you are using. For specific database information, see “Preparing to Configure an Alternative Database” in SAS 9.4 Intelligence Platform: Installation and Configuration Guide. However, instead of using SharedServices as the default name, you can use the following default values for setting up the database: n Database Name - DecisionServices n Name - DecisionServices n Schema Name - monitor

Note: The name must remain as DecisionServices. If the values for the database name, schema, and have been changed, additional changes are needed. 4

On the SAS Decision Services Engine Server, locate the corresponding SQL files for the database that you are migrating to. Navigate to <SASHome> \SASDecisionServicesEngineServer6.4/Config\Deployment\Data \ , and copy the SQL files to a location on the target database server. If the schema name has been changed from the default “monitor,” update the SQL file with the new schema name.

5 Using the appropriate database vendor SQL utilities, execute the create-

dcsv-tables-manual.sql file to load tables. 6 Edit the data-topology.sql file to include the SAS Decision Services Engine

host name (fully qualified domain name or IP address) and port, and then execute this SQL file. The default contents of this file are as follows: INSERT INTO monitor.DCSV_TOPOLOGY values ('@hostname.domain@', @engine.port@);

136 Chapter 3 / Setting Up the Environment Where @hostname.domain@ is the host name of the SAS Decision Services Engine Server. You can insert additional lines into this file for each SAS Decision Services Engine Server in your topology. @engine.port@ is the port number for the SAS Decision Services Engine. By default, this is port 8680. For example, the statement might look like this: INSERT INTO my_new_schema_name.DCSV_TOPOLOGY values (‘designserver.engine.hostname.com’, 8680);

7

If you have decided to change the schema name, then update the sasds.data.schema and sasds.engine..log.schema properties to use the new name. To update the properties: a Launch SAS Management Console. b

On the Plug-ins tab, navigate to Application Management  Configuration Manager  SAS Application Infrastructure  Decision Services Monitor 6.4.

c Right-click Decision Services Monitor 6.4 and select Properties. d

Select the Advanced tab.

e Locate the sasds.data.schema property in the list and change the schema

name to use the name that you have chosen. Here is an example of the property with the default setting:

f

Click OK to save the change.

g On the Plug-ins tab, navigate to Application Management  Configuration Manager  SAS Application Infrastructure  Decision

Services Monitor 6.4.

8

h

Right-click Decision Services Monitor 6.4 and select Properties.

i

Select the Advanced tab.

j

Locate the sasds.engine..log.schema in the list and change the schema name to use the name that you have chosen.

k

Click OK to save the change.

On the middle-tier server, navigate to the server.xml file for the application server where SAS Decision Services Monitor is running. By default, this file is located in SASServer7_1 under the <SAS-configuration-directory>/ Lev1/Web/WebAppServer/SASServer7_1/conf directory. Open the server.xml file for editing. In the server.xml file, locate this resource:

Managing Databases a

b

137

Modify the driverClassName to use the driver of the database that you have chosen to migrate to. Your choices are: Database

Driver Name

DB2

com.ibm.db2.jcc.DB2Driver

Greenplum


Netezza

org.netezza.Driver

Oracle

oracle.jdbc.driver.OracleDriver

PostgreSQL

org.postgreqsl.Driver

SQL Server

com.microsoft.sqlsever.jdbc.SQLServ erDriver

Teradata

com.teradata.jdbc.TeraDriver

In the JDBC URL string, modify the host name to point to the host and port of the database server. For example, if you have chosen to manually configure SAS Decision Services to use a different database, then the URL string would look similar to this example: url=”jdbc:oracle:thin:@//oraclemachine1.example.com:1521/ ”

9

Launch SAS Management Console to update the $_Log_JDBCConnection Resource for the SAS Decision Services design engine. Select the Folders tab and navigate to Applications  SAS Decision Services  Decision Services 6.4  SASDSEngineRepository. Right-click $_Log_JDBCConnectionResource and select Edit System Resource. Modify the following properties in the $_Log_JDBCConnectionResource system resource with the: n Driver Class: Enter the database JDBC driver class. n Server URL: Enter the database JDBC URL. n Enter the name and for the database.

10 Launch the SAS Deployment Manager to change the for the

DecisionServices database. a Select Update s. Click Next. b

Select the configuration directory. Click Next.

c

Enter the SAS istrative ’s . Click Next.

d Enter the of the web infrastructure database . Click Next. e

Select the DecisionServices ID in the IDs list. Click Next.

f

Enter the new . Click Next. Allow the SAS Deployment Manager to complete, and then close the application.

138 Chapter 3 / Setting Up the Environment Note: Completing these steps updates the catalina.properties file under SASServer7 with the encoded for the database. Therefore, if you have changed the from what it originally was, then completing the previous steps properly encodes it for use by the web application. 11 On the middle tier server, copy the database vendor JDBC JAR file (or if

applicable to your database server, multiple files) into the <SASconfiguration-directory>\Lev1\WebAppServer\SASServer7_n\lib directory. 12 Restart SASServer7_1, and make sure that you can log on successfully. 13 Validate that the new database connection is working as expected by running

the SAS Decision Services Diagnostics page. For example, access the following URL: http://middletier.machine.com:7980/DCSVMonitor/jsp/ Diagnostics.jsp. If the connection to the database is working as expected, then the report runs cleanly. If it is not set up properly, then a failure will be reported.

Creating Reporting Catalogs Overview of Reporting Catalogs You can use DS2 as the method for recording history transactions for your campaigns to the common data model. The history recording process for DS2 code requires that reporting catalogs be created in SAS Federation Server. A catalog must be created for the common data model library for each business context. For more information about SAS Federation Server catalogs, see SAS Federation Server: ’s Guide at http://.sas.com/ documentation/onlinedoc/fedserver/index.html.

Identify the Library for the Business Context To identify the reporting library for the business context: 1

In SAS Customer Intelligence Studio, open the Properties window for the business context. The reporting library for the business context is identified in the Common data model libref field on the Settings tab.

Creating Reporting Catalogs

139

Figure 3.3 Reporting Library for Business Context

2

In SAS Management Console, right-click the library name in the Data Library Manager plug-in and select Display LIBNAME Statement. Figure 3.4 Display LIBNAME Statement

3

Note the libref value in the LIBNAME statement. You will use the libref value when you create the cata SAS Federation Server. Figure 3.5

Libref Value “CIORA” in LIBNAME Statement

140 Chapter 3 / Setting Up the Environment Note: Schema names are case-sensitive. For SQL Server, the libref value should be the database name.

Create a Database Shared and Domain for SAS Federation Server A Data Source Name (DSN) is a persistent identifier that is associated with a data source definition. To access a DSN on SAS Federation Server, create new authentication domains and add information. The DSN is used as a pointer to the SAS Federation Server data service definition where the domain names are stored. A SAS Federation Server data service contains connection information to ed data sources such as Oracle. Part of the data service definition includes a reference to a domain name. The domain name is used to find outbound credentials to the database. The data source definition specifies how to locate and access a data source, including any authentication (such as a name and ) that a must provide. SAS Federation Server requires both a data service domain and a shared domain for granting group access to a data source. For more information, see SAS Federation Server Manager: ’s Guide. Note: Use SAS Federation Server Manager to that the DSN is accessible through other mechanisms. The SAS Decision Services Database s group has been created in the SAS Management Console Manager plug-in to enable s to access data using shared credentials. To add a new shared and domain to this group for use in SAS Federation Server: 1

Log on to the SAS Management Console as an istrative .

2 On the Plug-ins tab, select the Manager plug-in. 3

Right-click the SAS Decision Services Database s group and select Properties.

4

Click the s tab.

5 To create the data service domain and : a

Click New.

b

In the New Properties dialog box, do the following: i

Enter the ID for the shared to the database.

ii

Enter the for the .

iii Confirm the . iv Click New to set up a new domain. v

In the New Authentication Domain dialog box, enter the name for the new domain.

vi Select the Outbound only check box.

Create a Database Shared and Domain for SAS Federation Server

141

Figure 3.6 New Authentication Domain Dialog Box

vii Click OK to finish creating the new authentication domain. viii Click OK to finish creating the new . 6 To create the shared domain and : a Click New. b In the New Properties dialog box, do the following: i

Enter the ID for the to the database that you used in Step 5b.i on page 140.

ii

Enter the for the .

iii Select New to set up a new domain. iv In the New Authentication Domain dialog box, enter the name for the

new domain. Note: If you are creating a shared and domain for SAS Federation Server, the authentication domain must be in this format: @SASDS where is the domain name and SASDS is the shared key that is already configured on SAS Federation Server for use with shared groups. v

Select the Outbound only and Trusted only check boxes.

Figure 3.7 New Authentication Domain Dialog Box

vi Click OK to finish creating the new authentication domain. vii Click OK to finish creating the new shared . 7

Click OK to save changes to the SAS Decision Services Database s group.


Create a Database Shared and Domain for the JDBC Connection Resource JDBC connection resources can enable s to connect directly to the database. An example of a JDBC connection resource is $GeneralIO_Activity_Resource. The SAS Decision Services Database s group has been created in the Manager plug-in in SAS Management Console to enable s to access data using group credentials. To set up a new group and domain for use with a JDBC Connection resource: 1 Log on to the SAS Management Console as an istrative . 2

On the Plug-ins tab, select the Manager plug-in.

3 Right-click the SAS Decision Services Database s group and select

Properties. 4

Click the s tab.

5

Click New.

6

In the New Properties dialog box, do the following: a Enter the ID for the to the database. b Enter the for the . c Confirm the . d

Click New to set up a new domain.

e

In the New Authentication Domain dialog box, enter the name for the new domain.

f

Select the Outbound only check box. Figure 3.8 New Authentication Domain Dialog Box

g

Click OK to finish creating the new authentication domain.

h

Click OK to finish creating the new shared .

7 Click OK to save changes to the SAS Decision Services Database s

group.

Business Contexts

143

Business Contexts Overview of Business Contexts A business context defines the campaign-related information that an individual can access. To enhance information security, you can assign separate business contexts to ensure that individuals and groups have access only to the campaign-related objects that are required for their business units. Most sites use only one business context for SAS Real-Time Decision Manager.

Create a Business Context To create a business context, select the Business Contexts category in the Setup workspace. Click to create the business context. For more information, see SAS RealTime Decision Manager: ’s Guide. When you sign out from SAS Customer Intelligence Studio, all business contexts that have not been modified are automatically saved.

Asg Permissions for Business Contexts You must add s and groups to the appropriate roles before you can give them View or Edit permission for a business context. You can limit business context access to only groups by using an istrative to create all of the business contexts for your site. When the istrative first creates a business context, that is added by default to the Permissions tab and to the s tab of the business context Properties window. The istrative can add groups to the Permissions and s tabs, and then remove the istrative ID from both tabs. Note: If you remove a from the business context, that will receive an explicit metadata deny on the business context object. Even if they get an allow permission from a group hip, they cannot access the business context. In this instance, you must use SAS Management Console to remove the deny access control template for the . CAUTION! s who are listed in the SAS Customer Intelligence ACT (access control template) should not create business contexts. These s are excluded from the permissions list for business contexts. If they create business contexts, no other s will have permission, and no s will be listed on the permissions list.

New s and groups might not have immediate access to a business context. By default, the cache of permissions for a business context is refreshed every four hours. To modify the refresh interval, enter the following code in the Server_Name/bin/setenv.sh file of the web application server. -Dcom.sas.analytics.crm.bctx.cache.recache.minutes=number of minutes

144 Chapter 3 / Setting Up the Environment Node permissions are set separately from the business context permissions. For more information, see SAS Real-Time Decision Manager ’s Guide.

Managing Permissions for s and Groups The Permissions tab lists the s and groups who can have access to the business context definition in the Setup workspace. To add a to the list, click click

and select a . To add a group to the list,

and select a group.

To view the of a group, select the group and click

.

To change the permission of a or group, click the Permission cell and select the permission. By default, all s and groups that you select have Edit permission. In general, the permission that you set for an individual overrides the permission that is set for a group that the is a member of. For more information about the relationship of permissions between s and groups, see SAS Intelligence Platform: Security istration Guide. If you set a permission to View, the can see the business context in the Setup workspace, but cannot save any changes to the business context. Edit permission enables the to see the business context and to save changes to it.

Setting Up Business Context Directories Here are suggested subdirectories for the Business Context directory in your operating system: Note: Grant Read and Write permissions for the Business Context directory to the SAS group that manages the business context. Subdirectory Name

Contents

Data

external data used by SAS Customer Intelligence

Code

SAS code that is used in SAS processes

Deployment

deployment scripts

Documents

exported diagrams, backup information maps, and other campaign-related documents

Reporting

jobs, code, and data for the integration of SAS Customer Intelligence and SAS Visual Analytics

It is a best practice to use the Manager plug-in in SAS Management Console to create the following metadata groups for business context s:

Understanding Information Maps

145

<Business Context Name> Context s includes s who are allowed to sign in to SAS Customer Intelligence Studio. <Business Context Name> Context Approvers includes s who are approval-enabled for campaign definitions. <Business Context Name> Context s includes s who have istrative privileges for the business context. Grant the Customer Intelligence: Usage role to all groups. Here is a suggested metadata file directory structure that you might want to create on the Folders tab in SAS Management Console for the Business Context directory:

Understanding Information Maps For the business context, you must use SAS Information Map Studio to create an information map. Information maps enable you to do the following: n define an easy-to-use presentation layer for your underlying database data n use familiar business names to label folders and data items instead of using

database tables and fields directly n pre-define s among the data tables that you use

In SAS Real-Time Decision Manager, an information map is used to identify which fields will be used in the prompts for the history-related tasks in SAS Customer Intelligence Studio. In particular, an information map identifies the Subject and History fields for writing to the Customer Intelligence Common Data Model database. A Subject field is the identifying field for the primary person or thing with which your campaign is interacting. In inbound campaigns,

146 Chapter 3 / Setting Up the Environment the Subject field is almost always a customer ID or ID. Here is an example of the contents of an information map. The self-learner process uses the information map to determine which subsets of customer are more likely to respond to which treatments. The list of data items that are available in the self learner process comes from the information map. Figure 3.9

Information Map Contents

Creating an Information Map Tables Include the following basic tables: n the CUSTOMER table from your marketing Data Mart (or another primary

Subject table that has an identifier to with the CUSTOMER_ID field of the Customer Intelligence Common Data Model) n the CI_RESPONSE_HISTORY table from the Customer Intelligence

Common Data Model database n the CI__HISTORY table from the Customer Intelligence Common

Data Model database n the CI_PRESENTED_TREATMENT_HISTORY table from the Customer

Intelligence Common Data Model database

Creating an Information Map

147

these tables by using the CUSTOMER_ID field from the history tables and the primary key for customer from your CUSTOMER table.

Save the information map to a directory in metadata. For example, you might save the information map as /Shared Data/Customer Intelligence/ BusinessContexts/Telco/RDMTelcoMap

Add Custom Properties After you add the tables and define the field to use to them, add the following custom fields to the root level of the information map. The root level is the level at the top of the information map that is displayed in SAS Information Map Studio. In Figure 3.9 on page 146, the root level is RDMTelcoMap. Figure 3.10

Information Map Custom Properties

To add custom properties to a SAS Information Map at the map level, folder level, or data item level: 1

Open the information map in SAS Information Map Studio.

2

In the Information Map Contents pane, right-click the information map, folder, or data item, and select Properties.

148 Chapter 3 / Setting Up the Environment Figure 3.11 Folder Properties

3

Click the Custom tab.

4 If an Untitled1 row is not already displayed, then click Add to create a new

row. Otherwise, click in the right side of the Untitled1 cell to view the dropdown list of custom properties that are available, and select a custom property.

Creating an Information Map Figure 3.12

5

149

Custom Properties

The names of some of the custom properties are incomplete, such as Subject_ID_. To enter text in a cell, double-click in the cell. For more information, see “Custom Properties (Map Level)” on page 151.

6 After you enter the name, description, and value for a new custom property,

click within a header cell to remove the highlighting from the new row. If you click OK while any part of a row is highlighted, then the changes in that row are not saved. 7

Add the custom properties that are required for the map level. For more information, see “Custom Properties (Map Level)” on page 151.

8

To exit and save the new custom properties, click a heading cell or an existing row to remove the highlighting from any attribute, and then click OK.

Make Custom Properties Available 1 In SAS Information Map Studio, select Tools  Options. 2 On the Advanced tab in the Options dialog box, select the Custom

properties at start-up check box. 3

Specify the MAtemplate.txt file. The file is installed on the SAS server tier. On UNIX, the typical location is /local/install/SASServer/SASHome/ SASFoundation/9.4/misc/ma.

150 Chapter 3 / Setting Up the Environment On Windows, the typical location is \local\install\SASServer\SASHome \SASFoundation\9.4\ma\sasmisc. The location might be different for your site. 4

Click OK to close the Options dialog box.

5

Restart SAS Information Map Studio to apply the new setting.

Add Data Item Custom Properties Add the following Data Item custom properties for the primary key field for each of the following tables in the information map:

n CUSTOMER table (or the equivalent subject table from your marketing Data

Mart) n History Tables o

_History

o

Responses

o

Presented_Treatments Note: You must manually add Presented_Treatments to your custom properties because Presented_Treatments is not included in the custom properties template.

SAS Customer Intelligence Studio uses these custom properties to determine the prompts to show you when you are configuring history storage details for your business context. After you create the information map and save your changes, enter the path to your map’s metadata directory in the Information Map tab of your business context in SAS Customer Intelligence Studio.

Creating an Information Map

151

Custom Properties (Map Level) In the example values in the following table, the two subjects are Customer and Household. The table lists the extended attributes for a SAS Customer Intelligence information map. Table 3.15

Custom Properties (Map Level) That Are Related to Subject

Label

Description

Example Value*

Required?

FilteredTableExport

affects the refinement of export behavior. If FilteredTableExport is set to True, then when a subject is specified to be exported, at least one line for every subject is exported.

True

no

DataSetOptions_ engine

sets the data set options for the specified engine. This setting applies to all of the tables that access data through that engine.

DataSetOption s_ ORACLE=orhin ts=’/* */”

no

From_Subject_ID_ subjectname1_

is defined for each relationship between the valid subjects on the source tables. An entry is necessary for each direction of the relationship. These are valid relationships:

From_Subject_ ID_Customer_ To_Subject_ID _Household= ManyToOne

yes

To_Subject_ID_ subjectname2

n OneToOne n OneToMany n ManyToOne

From_Subject_ ID_Household_ To_Subject_ID _Customer= OneToMany

n ManyToMany*

* Not recommended. If the cells or lists of customers are created, duplicates are deleted. MetadataTable_Prefix_ Subject_ID_subjectname (for example, MetadataTable_Prefix_ Subject_ID_Customer)

is the prefix name for the SAS data sets that contain the generated data (the counts metadata). This is also the prefix name of data items for which NoMetadata extended attribute is set to False. Only one extended attribute per subject should exist.

Customer

yes

152 Chapter 3 / Setting Up the Environment Subject_Code_Subject_ID__ subjectname

associates a two-digit code with a subject. Only one extended attribute per subject should exist. This code is encoded as part of the ResponseTrackingCode that is a mandatory column to be ed to SAS Customer Intelligence Common Services. This code enables SAS Customer Intelligence Common Services to determine which subject table to write the responses and the presented treatment rows to.

Subject_Code_ Subject_ID__ Customer = 01

yes

Subject_Default

is the default subject extended attribute to be used throughout the information map for any data items where an associated subject extended attribute has not been explicitly set.

Subject_ID_Cu stomer

yes

Subject_ID_subjectname

is established for each subject as a unique extended attribute. Only one such extended attribute exists per subject. This subjectname is used in many places for other extended attribute values.

Customer

yes

(for example, Subject_ID_Customer)

The value appears in the Subject drop-down list in the Select Data Item dialog box in SAS Customer Intelligence. The actual physical data field name that makes up this subject is defined at the data item level. * The default value for all extended attributes is - .

Deg and Testing Campaign Components For information about creating, deg, and testing campaign components, see “Deg Campaigns” in SAS Real-Time Decision Manager: ’s Guide.

153

4 Integrating with the Customer Channel Integrating with the Customer Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Integrating with the Customer Channel through SOAP . . . . . . . . . . . . . . . . . . . . . 153 Retrieve a WSDL File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Integrating with the Customer Channel through the REST API . . . . . . . . . . . . . . 158 Post-installation Steps for REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Integrating with the Customer Channel through the Client API for Java . . . . . . 159 Integrating with External Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Integrating with the Customer Channel The SAS Decision Services Engine Server is seen externally as a web service endpoint. Customers’ external applications request decisions by sending web service requests to SAS Decision Services through SOAP, the REST API, or a Java API. In response to these requests, the engine server launches events and executes decision flows. Web services are used to kick off a flow. Integrating with the web services is an interaction that occurs inside a flow. To request information to be used downstream in a decision flow, you must create a web process that invokes a remote web service. You define the SAS processes to use in campaigns. For more information about creating web processes and SAS processes, see SAS Real-Time Decision Manager ’s Guide.

Integrating with the Customer Channel through SOAP When the SAS Decision Services web service endpoint is triggered by a Simple Object Access Protocol (SOAP) event request, the web service maps the incoming request to an event object in SAS Decision Services and es it to the run-time engine for processing. After the run-time engine has completed its processing, a SOAP response is serialized back to the invoking client. One-way event operations are also ed, which do not follow the common request and response message exchange pattern just described. In this case, a client sends a request and does not expect a response. Specifically, SAS Decision Services s SOAP document-style encoding, also known as documentliteral or message-style encoding. Of the three most popular SOAP encoding styles, SOAP RPC, SOAP RPC-literal, and document-literal, the document-literal style has the least overhead and highest performance. SOAP event requests from the customer application can be sent synchronously or asynchronously. A response from SAS Real-Time Decision Manager is

154 Chapter 4 / Integrating with the Customer Channel required if requests are sent synchronously. If the requests are sent asynchronously, a response is not required. The variables in the SOAP messages are accessed by name, and the order of declaration is not significant. In particular, the variables in the SOAP messages are independent of the order of the variables that are defined in the request and reply message sections of the event definition. Consequently, the variables in the request SOAP message do not have to be in the same order, as defined in the request message section of the event definition. Also, the SOAP client cannot rely on the variables in the reply SOAP message to be in any particular order, such as the order as defined in the response message section of the event definition. After creating an event and mapping that event to a decision flow, you can deploy the flow to a running instance of the SAS Decision Services Engine Server. After the decision flow is activated, the event can be invoked by a web service client. Here is a sample instance of a SOAP request that calls an event named "CustomerCall": <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:rtdm="http://www.sas.com/xml/schema/sas-svcs/rtdm-1.1"> <soapenv:Header/> <soapenv:Body>

100 Antarctica/South_Pole

10001

Here are the components of a sample SOAP request: Event name

Header fields 100 Antarctica/South_Pole

Request variable name

Request variable data type

Request variable value 10001

Because requests to SAS Decision Services can originate from multiple time zones, ClientTimeZoneID is a required field in the SAS Decision Services header. Time zone names from the public domain time zone (TZ) database are

Integrating with the Customer Channel

155

accepted. The public domain time zone database is maintained by the Internet Assigned Numbers Authority, available at http://www.iana.org/time-zones. The value in the optional Identifier field in the SAS Decision Services header is used as an identifier for the request message in logs. Every web service stack has client tools that can be used to generate both stubs and helper classes that call particular web services. These toolsets take a web service's WSDL file as input and generate the stubs and helper classes as output. Clients can be plain Java or .Net applications or, in a J2EE setting, they can be J2EE application clients or J2EE web applications themselves. For information about acquiring the WSDL in SAS Management Console, see “Retrieve a WSDL File” on page 156. Here is an example of a response from the SAS Decision Services Engine to a SOAP request: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <EventResponse name="NBO" xmlns="http://www.sas.com/xml/schema/sas-svcs/ rtdm-1.1">

100 <StartTime>2012-04-22T13:16:39.198-04:00 2012-04-22T13:16:39.861-04:00

<String> NORMAL <String> TRT0 <String> facebook.jpg <String> 5400010301 <StringArray> 325FD31F193DACB319E314EA6704F915

156 Chapter 4 / Integrating with the Customer Channel Here are the components of a sample response from the SAS Decision Services Engine to a SOAP request: Identity value echo 100

Response variable name

TIP Include the ResponseType reply field to notify the channel if this is a Normal, Error, or Standard reply. The engine server does not automatically include information about the type of reply that it is sending back. If the customer does not fit into any categories that are defined by a branch node, or if the customer does not meet the filter node criteria, then that customer will receive a Standard reply. If the execution for the decision campaign times out before the execution logic has completed, then a Standard reply is returned. An Error reply occurs if one of the nodes threw an error. The Normal reply occurs when the execution logic of the decision campaign has completed. Otherwise, you must navigate to the SAS Decision Services log to determine the value of the reply.

Response variable data type <String>

Response variable value NORMAL

Response tracking code <String> 5400010301

Treatment tracking codes <StringArray> 325FD31F193DACB319E314EA6704F915

Retrieve a WSDL File You can retrieve a specific Web Service Definition Language (WSDL) file for a given Decision Services event as follows: 1

Open SAS Management Console.

2 On the Folders tab, select System  Applications  SAS Decision Services  Decision Services 6.4. 3 Navigate to the SAS Decision Services repository for which you want to

generate a WSDL. 4 Right-click the web service event in the repository and click Export WSDL.

Integrating with the Customer Channel 5

157

For events that require a reply, select the Request/Reply WSDL Type. For events that do not require a reply, such as presented treatment histories or record histories, select the Asynchronous WSDL Type.

6 Modify the default address for your environment. Here is a sample address:

http://localhost:9086/RTDM/Event. The address is determined during the installation of your software. 7

Navigate to a location to store and name the WSDL file.

Figure 4.1 WSDL File

8

Click Save. Figure 4.2 WSDL Created

You can browse your file system to that the new WSDL exists.

158 Chapter 4 / Integrating with the Customer Channel Figure 4.3 Exported WSDL

Integrating with the Customer Channel through the REST API Note: Post-installation steps are required for the REST interface to work properly. For more information, see “Post-installation Steps for REST API” on page 159. This API allows access to decisions that are generated by the SAS Decision Services Engine. Specifically, the API accepts inputs that are represented as decision parameters, processes them in the engine, and returns a representation of the decision generated. The API is implemented as a Representational State Transfer (REST) interface that accepts JavaScript Object Notation (JSON) payloads. The REST API generates events in the SAS Decision Services Engine. To generate an event, a client application posts a flow to a named event definition and receives an event in response. The request includes a set of name-value pairs that serve as inputs to the event generation process. Each binding has a name that is a string and a value. The value might be a number, a Boolean value, a string, an array, or a table. The generated flow contains a set of namevalue pairs that are used by the client applications to implement an event. For example, a call center might use an event that contains items to offer to a customer for sale. Each event definition has a required set of name-value pairs with fixed names and types for the event request as well as a defined set of name-value pairs for the corresponding flow that was produced. A SAS Decision Services Engine might hold several flows. Each such flow contains code that generates a flow when it is executed. Each flow is associated with only one decision definition that determines the inputs and outputs and that is an interface to the flow. The client application does not reference the flow directly. Rather, it uses the decision name that is defined in the event definition. When an event request is received by the engine, it looks up the event definition with the supplied event name, finds the flow that is associated with the event definition, executes the flow, and returns the generated event. Here is an example of a REST API request to the SAS Decision Services Engine: Note: Event names cannot include spaces. {"clientTimeZone":"Antarctica/South_Pole", "identity":"{3F2504E0-4F89-41D3-9A0C-0305E82C3301}" "inputs":


159

{ "string":"Foo", "stringArray":["One","Two","Three"], "boolean":true, "booleanArray":[true,false], "dateTime":"2014-05-29T21:49:26.577Z", "dateTimeArray":["2014-05-29T21:49:26.577Z","2014-05-29T21:56:28.078Z"], "decimal":3.14, "decimalArray":[1.1,2.2], "integer":42, "integerArray":[1,2], "table":[ {"metadata":[{"tvar1":"string"},{"tvar2":"boolean"},{"tvar3":"dateTime"}, {"tvar4":"decimal"},{"tvar5":"integer"}]}, {"data":[ ["Blah",true,"2014-05-29T21:49:26.577Z",0.5,7], ["Bar",false,"2014-05-29T21:56:28.078Z",3.14,42]]}] }}

Post-installation Steps for REST API In order to for the REST API to work correctly, the following post-installation steps must be completed: 1

Find the sas.conf file in the conf folder of the SAS web server installation <SAS-configuration-directory>\Web\WebServer\conf.

2

Find the two lines of code that define the proxy and reverse proxy for the SAS Decision Services Engine.

Proxy /RTDM balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /RTDM balancer://<machine name>.na.sas.com_Cluster7/RTDM 3 Copy these lines of code to a text editor and change the /RTDM on the right

side of the mapping to /SASDecisionServices as follows: Proxy /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM 4

Paste these modified lines of code directly below the lines mapping /RTDM.

Proxy /RTDM balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /RTDM balancer://<machine name>.sas.com_Cluster7/RTDM Proxy /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM 5 After editing the file, restart the SAS web server.

Integrating with the Customer Channel through the Client API for Java The SAS Decision Services Client Application Programming Interface (API) for Java is a set of Java classes that enables Java applications to stream events to the SAS Decision Services Engine for high-performance execution. The SAS Decision Services Client API for Java provides a high-performance alternative to SOAP by using an efficient, proprietary protocol that marshals messages over HTTP. Using this API, a Java application can avoid the overhead associated with

160 Chapter 4 / Integrating with the Customer Channel parsing and generating XML messages in SOAP, resulting in significantly improved system throughput.

Architecture of the Client API for Java The client API for Java uses the following primary interfaces: SASDSRequestFactory The first step to using the API is to instantiate a factory object by calling the getInstance method on SASDSRequestFactory interface. This method accepts two parameters, the URL of the SAS Decision Services Engine and a properties file. Apache HTTP Client is used to communicate with the SAS Decision Services Engine. The properties file can be used to tune this HTTP Client. Using the factory object instance, call the create method to create a request object using three parameters: the name of the event that you want to use, a correlation ID for matching responses to requests, and a time zone identifier. The SAS Decision Services Engine uses the time zone identifier as the default time zone for processing the request. The create method is thread safe and can be used by multiple threads to drive the interface in parallel to achieve high throughput. SASDSRequest This request object is used to assign values to the event request variables before executing the event. It has typed getter and setter methods that can be used to read or set the request data. After setting the values, call the execute method to execute the event in the SAS Decision Services Engine and to retrieve the response. If the SAS Decision Services Engine returns a fault, an exception is thrown from the execute method. Otherwise, the method will return a SASDSResponse object. The SASDSRequest object is not thread safe and can be used only for a single event execution. Calling execute multiple times will result in an IllegalStateException. SASDSResponse This response object is returned from the execute method upon successful event execution. It has getters that return the various fields of the event response, including the processing start and end times, and the values of the event response variables. Like the SASDSRequest object, the accessor methods are strongly typed.

Data Types The following table lists the ed event parameter types. Decision Service Type

Java Type

BOOLEAN

java.lang.Boolean INT java.lang.Long

FLOAT

java.lang.Double

DATETIME

javax.xml.datatype.XMLGregorianCalend ar

STRING

java.lang.String


161

SASDSRequest Interface Note: The SAS Decision Services Client API for Java cannot be used for marketing-style campaigns that require treatment tracking codes (TTC) because the API does not arrays or tables. Use the SASDSRequest interface to set or retrieve the values of the request variables that comprise your Decision Services event. The event, which includes request and response variable names and types, must be defined in SAS Decision Services. An event is specified for the SASDSRequest object when it is created. Here is an example of using the client API for Java to set or retrieve the values of the request variables that comprise your Decision Services event: // get a factory SADSRequestFactory=getInstance("http://sasbap.demo.sas.com/RTDM/Custom", "file://path/to/file.properties"); // Create the request SASDSRequest request = factory.create("PT_SimpleVariableEcho_Event", Long.toHexString(System.currentTimeMillis()), "GMT"); // Populate request request.setString("in_string", "hello"); request.setLong("in_int", 1L); request.setDouble("in_double", 1.2); request.setBoolean("in_bool", true); request.setXMLGregorianCalendar("in_date", df.newXMLGregorianCalendar(2012, 05, 05, 12, 00, 00, 00, 300)); // Execute event SASDSResponse response = request.execute(); // Extract results from response String actualOutput = response.getString("out_string");

Distribution The SAS Decision Services Client API for Java is distributed as a zip-encoded file containing a set of JAR files and other files that can be used to build and run the client application.

Integrating with External Web Services Invoking External Web Service Activities SAS Decision Services functionality can be extended by adding new web service activities. A web service activity can invoke an external web service that requests information to be used downstream in the decision flow. For example, suppose an organization has an inventory system with a web service interface. It is possible to create a web service activity that sends a request to the inventory system to check that there is sufficient quantity of a product to extend an offer. The web service activity maps leaf-level elements of a flat-structured XML, for the request and response payloads, to SAS Decision Services process variables of the following data types:

162 Chapter 4 / Integrating with the Customer Channel n BOOLEAN n INT n FLOAT n DATETIME n STRING n ARRAY OF BOOLEAN n ARRAY OF INT n ARRAY OF FLOAT n ARRAY OF DATETIME n ARRAY OF STRING

Web service activity s only transport-level security using SSL (HTTPS). The web service activity uses a Web Service Connection system resource. This resource contains the URL of the web service to invoke. When you publish a new web service activity, you bind it to a particular Web Service Connection system resource. Create your Web Service Connection system resource before publishing your new web service activity. For more information about the Web Service Connection system resource, see “Specify a New System Resource as a Web Service Connection” on page 125. For information about defining a web process in SAS Customer Intelligence Studio, see “Defining the Components of Campaigns” in SAS Real-Time Decision Manager: ’s Guide.

Invoking SAS BI Web Services SAS BI Web Services executes as SAS stored processes in the SAS server tier. The use of BI web services in real-time applications is not recommended because of their slow execution speed. Neither sub-second latencies nor high transaction volumes can be ed when SAS BI web services are used. Unless you need to run a procedure, use a DS2-based SAS activity instead. SAS BI web service activity s an extended set of data types. The standard web service activity s the types that are listed above. The SAS BI web service activity s the following input and output parameter types: Note: SAS BI web service activities return only string arrays. They cannot return float arrays. Table 4.1

Input Parameter Types

Stored Process Type

SAS Decision Services Type

Numeric (integer)

Int

Numeric (double)

Float

Text

String

Numeric (integer) with name ending in _b

Boolean

Numeric (integer) with name ending in _d

DateTime

Integrating with the Customer Channel Text with name ending in _a

String Array

Text with name ending in _t

Table

Table 4.2

Output Parameter Types

Stored Process Type

SAS Decision Services Type

Integer

Int

Double

Float

String

String

Integer with name ending in _b

Boolean

Integer with name ending in _d

DateTime

String with name ending in _a

String Array

String with name ending in _t

Table

Tables and arrays are ed in and out of the stored process as encoded strings. An autocall macro, called scencode, is provided to encode these objects. BI web service activity s only transport-level security using SSL (HTTPS).

163

164 Chapter 4 / Integrating with the Customer Channel

165

5 Creating Custom Code with DS2 DS2 Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Default SAS Decision Services 6.4 and SAS Federation Server 4.2 Configuration Settings for DS2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Parameter Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Using the Execute Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Testing Your DS2 Code with the SAS Federation Server . . . . . . . . . . . . . . . . . . . 167 Create a DS2 Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Examples of DS2 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Create a SAS Process Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Data Type Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Out of the Box SAS DS2 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Accessing Database Tables from a Custom SAS Activity or from a Business Rules Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 SAS Decision Services Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

DS2 Programming Overview DS2 is a SAS programming language for advanced data manipulation. DS2 is included with Base SAS and includes additional data types, ANSI SQL types, programming structure elements, and -defined methods and packages. Several DS2 language elements accept embedded FedSQL syntax and the runtime queries can exchange data between DS2 and ed databases. SAS process nodes can use DS2 code to customize functions in SAS Real-Time Decision Manager. The efficiency of this custom code can affect the speed and resource usage of campaigns.

Default SAS Decision Services 6.4 and SAS Federation Server 4.2 Configuration Settings for DS2 To enable the SAS Real-Time Decision Manager connection and execution of DS2 through SAS Federation Server 4.2, the first maintenance release of SAS Decision Services configures several things out of the box.

166 Chapter 5 / Creating Custom Code with DS2 In the first maintenance release of SAS Decision Services 6.4, changes were made to the following files in the /Applications/ SASDecisionServicesServerConfig/Utilities directory in the Server tier: n The sasds_fedserver_sas.sas file includes the following updates: o add the XSET PLSRCMGTSECURITY FALSE option to the Alter

Server statement o add a GRANT CREATE TABLE, SELECT, INSERT, DROP TABLE,

EXECUTE ON SERVER TO “SAS Decision Services Database s” AS ; statement o add a GRANT CONNECT ON DSN "&feddsn" TO "SAS Decision

Services Database s" AS ; statement (&feddsn represents the base_dsn) n The createFDSN.sas file includes the Add a GRANT CONNECT ON DSN

TO "SAS Decision Services Database s" AS ; statement update. n The sasds_fedserver.sas file includes the Set a group for the

database DSN: CREATE DSN &dbdsn under &dataservice NOPROMPT 'DRIVER=ORACLE;GROUP=''SAS Decision Services Database s''' {OPTIONS (CSO (SHARED, PERSONAL))} AS ; update.

On the SAS App tier with SAS Decision Services, the /Applications/ SASDecisionServicesServerConfig/Utilities/sasds_fedserver_sas.sas file contains the following statements that set the required SAS Federation Server properties: n ALTER SERVER {OPTIONS ((XSET SHAREDKEY SASDS), (XSET

PLSRCMGTSECURITY FALSE))}; n GRANT CREATE TABLE, SELECT, INSERT, DROP TABLE ON SERVER TO

“SAS Decision Services Database s” AS ;

To enable of the SAS Decision Services Database s group to connect and execute to the data service names (DSNs) for SAS Real-Time Decision Manager, the following SAS Federation Server option is issued out of the box by SAS Decision Services: ALTER SERVER {OPTIONS (XSET PLSRCMGTSECURITY FALSE) };. The SAS Decision Services Database s group is also granted CONNECT permission to BASE_DSN and DSFEDERATEDDSN. If a chooses to configure a third-party database out of the box, the database DSN that is created is set to use a Shared and the Shared group will be set to SAS Decision Services Database s. The Data Service for the database is also set to use the Authentication Domain that was configured by Decision Services

Parameter Limitations Each String parameter that is sent to or received from your DS2 code has a limit of 32 KB. Within a DS2 process, each list and data grid parameter is serialized to a single string with a limit of 32 KB. The size of a serialized table or list depends on the sizes and numbers of the data that it contains and the number of record and field separators. Therefore, avoid very large tables because they

DS2 Programming

167

cannot be transferred to or from a DS2 process. In some cases, it might be possible to separate data into multiple smaller tables. As a best practice, send only data that is necessary to a particular process. In order to subset data that is sent to the process, create a calculated variable that uses the TABLESELECT function. For more information about the TABLESELECT function, see SAS Real-Time Decision Manager: ’s Guide. The performance of custom arbitration and other uses of DS2 code might be significantly degraded if large amounts of data are processed because of network or serialization costs. The treatment tables transmitted to custom arbitration are reduced by columns referenced and can be configured to include custom details for only desired custom detail tags within the definition.

Using the Execute Method SAS Real-Time Decision Manager DS2 activities allow multiple DS2 packages per activity. The last package in an activity is the package that is associated with that activity. The execute method in that last package is the method that is executed when your DS2 activity is called from a decision flow. That execute method must be the last method in the DS2 code and must be in all lowercase letters in order for SAS Real-Time Decision Manager to recognize it. Note: Do not add a white space after method execute( in the DS2 code.

Testing Your DS2 Code with the SAS Federation Server To avoid errors, test your DS2 code with the SAS Federation Server that is configured for your environment. If you are testing DS2 code that uses the tap utilities packages, be sure to that the tap packages are available in the \Applications \SASDecisionServicesServerConfig\SASCode directory. For more information, see “Utility Packages” on page 175. Here is an example of DS2 code that you can use for testing: Note: You can obtain the PROC DS2 statement from the first line of the code in any of the provided tap utility packages. Be sure to modify the code to include the appropriate . proc ds2 nolibs noprompt="driver=remts;server=myServer;port=myPort; protocol=bridge;uid=myID;pwd='My';conopts=(driver=ds2; conopts=(driver=sql;conopts=(DSN=DSFEDERATEDDSN)))"; package arbReverse /overwrite=yes ; method execute( package tap_sqltable Treatments, package tap_sqltable Treatments_Custom, package tap_sqltable Treatments_Custom_List, int Arbitration_Count, in_out package tap_int_array Treatments_Order ); dcl int count; Treatments_Order.clear();

168 Chapter 5 / Creating Custom Code with DS2 if Treatments.is_null() then do; Treatments_Order.set_null(); end; else do; count = Treatments.row_count(); Treatments.rowLast(); do i = count to 1 by -1; Treatments_Order.add(Treatments.getInt('TREATMENT_ID')); Treatments.rowPrevious(); end; end; end; endpackage; run;quit;

To test DS2 code, run the code in Base SAS to validate that the DS2 code contains no syntax errors and to publish the code to the SAS Federation Server. Log files for the test appear in the log window in Base SAS and in the SAS Federation Server log directory (\Lev1\FederationServer\var\Logs). For information about resolving errors in the logs, see Appendix 1, “Troubleshooting,” on page 307. For more information about testing DS2 code, see SAS 9.4 DS2 Language Reference.

Create a DS2 Package A DS2 package is an object containing a set of associated methods that perform specific functions, similar to a class in an object-oriented programming language. SAS Decision Services enables you to create and use SAS DS2 packages that are compiled and run by SAS Federation Server. This functionality uses the SAS Federation Server internal copy of the SAS DS2 compiler and engine. The SAS Federation Server internal version of SAS DS2 might be slightly older than the Base SAS internal version of SAS DS2. When you are troubleshooting a problem, you might need to determine whether the problem is related to mismatched versions of SAS DS2. Create your DS2 package in an interactive SAS session. This method enables you to conduct immediate testing to be sure the code is correct. DS2 packages are created using PROC DS2. For more information about PROC DS2, see SAS 9.4 DS2 Language Reference. Note: Be sure to test your DS2 package using the same version of SAS that is used in SAS Customer Intelligence. Be sure to set the NOPROMPT option in your PROC DS2 statement to point to your design or test SAS Federation Server. This ensures that the version of SAS used to compile your DS2 activity matches the version that is used by SAS Decision Services at run time. proc ds2 nolibs noprompt="driver=remts;server=your_Fed_Server;port=21032; protocol=bridge;uid=;pwd=; conopts=(DSN=DSFEDERATEDDSN)"; ds2_options sas;package my_pkg /overwrite=yes

DS2 Programming

169

method execute(varchar(32767) in_string, in_out varchar out_string); out_string=in_string; end; endpackage; run; quit;

This code creates a package that is called my_pkg that contains one method, execute(), and stores it in the database that is pointed to by DSFEDERATEDDSN. SAS activity methods must be coded as void functions in DS2. Output parameters must be marked with the in_out tag, which causes their values to be returned to the middle tier after method execution. Note: SAS Decision Services does not the use of in_out tagged parameters for input. They are used strictly for output only. Also, always ensure that all input arguments precede the output arguments within your DS2 method signatures. To force a package to always execute in SAS missing mode, use ds2_options sas; as the first statement, before the PACKAGE statement. When you omit this option, your package uses ANSI missing mode by default. SAS missing mode is recommended to achieve the highest compatibility between DS2 and DATA step. Your custom activity code might include more than one DS2 package. The methods of the last package in your DS2 program are the only methods that are visible to decision flows. The execute() method of the last package is the only method that can be called by the decision flows. The arguments for these methods must use only the Decision Services data types. Otherwise, an error is returned during the activity publishing step. Note: If you use SAS Business Rules Manager to create multiple business rules definitions that use the same rule flow, the rule flow DS2 code for the most recent business rules definition overwrites the DS2 code for previous rule flows because the DS2 package names are the same. For information about creating business rules, see SAS Real-Time Decision Manager: ’s Guide. You can test your package in your interactive SAS session by using a DS2 TABLE statement: proc ds2 nolibs conn="driver=remts;server=your_Fed_Server;port=21032; protocol=bridge;uid=;pwd=; conopts=(DSN=DSFEDERATEDDSN)"; table _null_; method init(); dcl package my_pkg echo(); dcl varchar(32767) out_string; echo.execute('String to echo', out_string); put out_string=; end; endtable; run; quit;

Note: The DSN value (DSN=DSFEDERATEDDSN) must point to the same DSN that is used in your $SAS_Activity_Resource. When you publish a new or modified SAS activity in the design environment, the activity is immediately made available for inserting into flows and for testing. After changing and republishing an existing SAS activity in a test or production environment, or after importing a modified SAS activity into a test or production

170 Chapter 5 / Creating Custom Code with DS2 environment, the engine picks up the new activity code the next time a flow is activated or deactivated. Until that time, any prior version of the activity continues to be used. The following table lists the code that defines, executes, and tests a DS2 package. Note: If you are using Base SAS to run the DS2 code, you use the code for Definition and Execution and Testing. If you are using SAS Customer Intelligence Studio to run the DS2 code, you use only the code for Definition. DS2 Package Structure Definition

Here is the pre-defined code package that must be called by another program in order to run. proc ds2; package XtimesY /overwrite=yes; method execute(int x, int y, in_out int result);

The following command can be invoked by any other internal method or by external code. result = x * y;

The following command runs immediately and automatically when the data statement is run. end; endpackage; run;

Execution and Testing

data _null_; method run(); declare package XtimesY xy(); declare int s; xy.execute(3, 12, s); put s=; end; enddata; run; quit;

Examples of DS2 Packages Example 1: Hello World! DS2 Program The following example shows a simple PROC DS2 program that displays Hello World! in the SAS log. proc ds2; data _null_;

DS2 Programming method dcl str put end; enddata; run; quit;

171

init(); varchar(16) str; = 'Hello World!'; str;

Without a currently assigned libref, the PROC DS2 statement simply sets up the environment to submit DS2 language statements. proc ds2;

_NULL_ on the DS2 DATA statement indicates that there is no automatic output generated. The DS2 PUT statement writes to the SAS log. Note: Use the PUT statement only for temporary troubleshooting. data _null_; method init(); dcl varchar(16) str; str = 'Hello World!'; put str; end; enddata;

The RUN statement submits the DS2 statements. The RUN statement is required. SAS reads the program statements that are associated with one task until it reaches a RUN statement. run;

The QUIT statement stops the procedure. quit;

The SAS log showing Hello World! appears as follows: 48 proc ds2; 49 data _null_; 50 method init(); 51 dcl varchar(16) str; 52 str = 'Hello World!'; 53 put str; 54 end; 55 enddata; 56 run; Hello World! NOTE: Execution succeeded. No rows affected. 57 quit; NOTE: PROCEDURE DS2 used (Total process time): real time 16.38 seconds u time 0.15 seconds

For detailed information about creating DS2 code, see SAS DS2 Language Reference.

172 Chapter 5 / Creating Custom Code with DS2

Example 2: SQL in a DS2 Program This example illustrates how to use an SQL statement in a DS2 program. To access the output from an SQL query, put the query in a SET statement. When the SET statement runs, it sequentially reads the rows that are returned by the query. The first DS2 program calculates annual balances for an into which contributions of $2000 are made every year from 2004 to 2014. The carries a 7% interest rate, compounded annually. The second program generates the table. The third program generates the results of an SQL query. The query selects all rows from INVESTMENT where the value of INVESTMENT_YEAR is greater than 2010. The example code is as follows: proc ds2; data investment; dcl integer investment_year; dcl double capital; method init(); capital = 0; do investment_year = 2004 to 2014; capital = capital + (2000 + .07 * (capital+2000)); output; end; end; enddata; run; data; method run(); set investment; end; enddata; run; data; method run(); set {select * from investment where investment_year > 2010}; end; enddata; run; quit;

The example output is as follows: INVESTMENT_YEAR

CAPITAL

2004

2140

2005

4429.8

2006

6879.886

2007

9501.478

2008

12306.58

DS2 Programming 2009

15308.04

2010

18519.61

2011

21955.98

2012

25632.9

2013

29567.2

2014

33776.9

INVESTMENT_YEAR

CAPITAL

2011

21955.98

2012

25632.9

2013

29567.2

2014

33776.9

173

Example: Reverse-the-Order Custom Arbitration Process The following example shows a basic DS2 custom arbitration package. package G_Arb_Reverse /overwrite=yes ; method execute( package tap_table Treatments, package tap_table Treatments_Custom, package tap_table Treatments_Custom_List, int Arbitration_Count, in_out package tap_int_array Treatments_Order ); dcl int count; Treatments_Order.clear(); if Treatments.is_null() then do; Treatments_Order.set_null(); end; else do; count = Treatments.row_count(); do i = count to 1 by -1; Treatments_Order.add(Treatments.getInt('TREATMENT_ID', i)); end; end; end; endpackage; run;


Create a SAS Process Definition 1

In SAS Customer Intelligence Studio, create a new SAS process.

2

On the Properties page, do the following: a Enter a SAS process ID. For DS2 code, the SAS process ID must match

the last DS2 package name that you enter on the SAS Code page. Note: The casing for the SAS process ID must also match the casing for the DS2 package name. b Enter a description that includes you as the owner and that describes the

purpose of the activity. 3

In the SAS Code page, copy and paste the DS2 package code that you tested in Base SAS. Note: You do not need the PROC DS2 statement when you copy and paste the DS2 package code into a SAS process definition. After you enter the code, the variables are automatically generated in the Input Variables and Output Variables pages. Note: Your DS2 package must contain the method execute().

The code and metadata are sent to the SAS Decision Services Design Server, which stores it in the design repository folder within SAS Metadata Server. After the package has been completed and stored in the repository, you can create flows that include the SAS process. For more information about creating SAS processes, see SAS Real-Time Decision Manager ’s Guide.

Data Type Mappings The following table lists the SAS Decision Services data types and the corresponding DS2 data types. When you create a flow or event, you work with the data types in the left column. When you write DS2 code, you use the data types in the right column. Note: DateTime fields contain SAS datetime values. Datetime values are the number of seconds since January 1, 1960. Table 5.1

Data Types

SAS Decision Services Data Type

DS2 Data Type

String

Varchar

Int

Bigint

Float

Double

Boolean

Integer

DS2 Programming DateTime

175

Double

Out of the Box SAS DS2 Packages Overview Several DS2 packages are provided out of the box, in the following location \Applications\SASDecisionServicesServerConfig \SASCode. Some of those SAS files are required by the SAS Decision Services

run time, some are utilities to help you build your own SAS activities, and some are sample SAS activities. Note: Do not modify these DS2 packages. Do not call methods that are marked as internal-use-only in the source code comments.

Utility Packages Note: To add logging to your custom DS2 packages, see “DS2 Logger Package Methods, Operators, and Statements” in SAS DS2 Language Reference. tap_hash This package is a simple extension of the DS2 hash object. Each new package does not need to declare its own hash extension package; this one is provided for everyone’s use. To reference this package, specify the package keyword, the utility package name, and then the DS2 variable name.declare package tap_hash my_hash();. tap_{data type}_array where the data type is string, datetime, float, int, or boolean

Note: It is recommended to use tap {data type}_array instead of tap_array. SAS Decision Services array objects are ed to a DS2 method as an encoded string (varchar) parameter. Use the tap_data type_array package to decode the string. This package must be used in the execute method so that SAS Customer Intelligence Studio can parse the parameters to determine which type of List variable to use for input and output. Empty array objects can also be created and populated by your custom SAS activity code. This package provides an encode() method that can be called to create an encoded string version of the current array. This is the array that is to be returned to the SAS Decision Services engine. Here are the available methods: n tap_data type_array(); - Constructs an empty array.

Note: set_type must be called immediately after using this constructor. n tap_data type_array(varchar input_array); - Constructs an array that is

initialized using the encoded input_array string. n set_type(varchar type); - Sets the type of array. Choose one of the

following types: STRING, INT, FLOAT, BOOLEAN, or DATETIME. This method is not case sensitive. n type() returns varchar; - Returns the type of array. Choose one of the

following: STRING, INT, FLOAT, BOOLEAN, or DATETIME.

176 Chapter 5 / Creating Custom Code with DS2 n encode() returns varchar; - Encodes this array into a string for return to

the SAS Decision Services engine. n add(varchar element); - Appends the specified element to the end of this

array. n add(int element); - Appends the specified element to the end of this array. n add(double element); - Appends the specified element to the end of this

array. n add(int index, varchar element); - Inserts the specified element at the

specified position in this array. n add(int index, int element); - Inserts the specified element at the specified

position in this array. n add(int index, double element); - Inserts the specified element at the

specified position in this array. n addAll(package tap_array in_array); - Appends all of the elements in the

specified array to the end of this array. n clear(); - Removes all of the elements from this array. n set_null(); - Sets this array to null. n getString(int index) returns varchar; - Returns the element at the specified

position in this array. n getInt(int index) returns int; - Returns the element at the specified position

in this array. n getDateTime(int index) returns double; - Returns the element at the

specified position in this array. n getBoolean(int index) returns int; - Returns the element at the specified

position in this array. n getFloat(int index) returns double; - Returns the element at the specified

position in this array. n isEmpty() returns int; - Returns 1 (true) if this array contains no elements,

0 (false) otherwise. n delete(int index); - Deletes the element at the specified position in this

array. n setString(int index, varchar element); - Replaces the element at the

specified position in this array with the specified element. n setInt(int index, int element); - Replaces the element at the specified

position in this array with the specified element. n setFloat(int index, double element); - Replaces the element at the

specified position in this array with the specified element. n setDateTime(int index, double element); - Replaces the element at the

specified position in this array with the specified element. n setBoolean(int index, int element); - Replaces the element at the specified

position in this array with the specified element. n size() returns int; - Returns the number of elements in this array.

Here is an example of using the tap_data type_array utility package: declare package tap_string_array my_out_array();

DS2 Programming

177

declare package tap_string_array my_in_array(); declare varchar(32767) test_output; /* DEBUG: Check and see what the input values look like */ test_output = my_in_array.encode(); put test_output=; /* Reverse the order of items in the input and return array */ do count = my_in_array.size() to 1 by -1; my_out_array.add(my_in_array.get(count)); end; /* DEBUG: Check and see what the output values look like */ test_output = my_out_array.toString(); put test_output=;

tap_table You use the tap_table method to manage SAS Decision Services data grids. Here are the available methods: Note: You can enter up to 32K characters in the varchar field. n tap_table(); - Creates an empty table. n tap_table(varchar input_table); - Creates a table that is initialized with the

input table string. n encode() returns varchar; - Encodes the table into a string that can be

ed back to the SAS Decision Services engine. n add_column(varchar name, varchar type); - Adds a column of the given

type to the table. n add_row(); - Adds a new row to the table, all values are set to null or

empty for string variables. n add_row(int rows); - Adds the specified number of rows to the table, all

values are set to null. n column_count() returns int; - Returns the number of columns in the table. n row_count() returns int; - Returns the number of rows in the table. n column_name(int index) returns varchar; - Returns the name of the

column at the given ordinal. n column_type(int index) returns varchar; - Returns the type of the column

at the given ordinal. n column_type(varchar name) returns varchar; - Returns the type for the

given column. n decodeJSON() - Initializes a tap_table instance using the given JSON

string. Note: For more information about the expected dialect of the JSON text, see “Using the tap_table Package decodeJSON and encodeJSON Methods” on page 183. n delete_column(varchar name); - Removes the given column from the

table. n delete_row(); - Removes the given row from the table.

178 Chapter 5 / Creating Custom Code with DS2 n encodeJSON() - Returns a nvarchar string, where the string is a JSON

representation of the tap_table instance. Note: If the format of your data does not agree with the default values, see “Using the tap_table Package decodeJSON and encodeJSON Methods” on page 183 n getString(varchar col_name) returns varchar; - Retrieves the string value

from the given column at the current row. n getInt(varchar col_name) returns bigint; - Retrieves the bigint value from

the given column at the current row. n getBoolean(varchar col_name) returns bigint; - Retrieves the Boolean

value from the given column at the current row. n getFloat(varchar col_name) returns double; - Retrieves the float value

from the given column at the current row. n getDateTime(varchar col_name) returns double; - Retrieves the datetime

value from the given column at the current row. n setString(varchar col_name, varchar element); - Sets the value of the

given column, at the current row, to the given string value. n setInt(varchar col_name, int element); - Sets the value of the given

column, at the current row, to the given bigint value. n setFloat(varchar col_name, double element); - Sets the value of the given

column, at the current row, to the given float value. n setDateTime(varchar col_name, double element); - Sets the value of the

given column, at the current row, to the given datetime value. n setBoolean(varchar col_name, bigint element); - Sets the value of the

given column, at the current row, to the given Boolean value. n set_null(); - Sets the table to null.

Here is an example of using the tap_table utility package: declare package tap_table factors_table(); declare int multiplier; declare int i; /* Setup the metadata for the output table */ do multiplier = 1 to 10; factors_table.add_column('times' || multiplier, 'Int'); end; /* add one row per number and populate multiplication table */ do i = 1 to 10; factors_table.add_row(); do multiplier = 1 to 10; factors_table.setInt(i, multiplier, i * multiplier); end; end;

DS2 RESTCallout The DS2 RESTCallout package provides a means to execute HTTP POST requests from DS2. It is a helper package that is a front end to the HTTP DS2 package. More specific requests might require the direct usage of the

DS2 Programming

179

DS2 HTTP package, when the use of specific DS2 HTTP package features is desired. Here are the available methods: tap_RESTCallout The constructor method creates a DS2 RESTCallout package instance. Its member variables include a varchar(2048) URL attribute, as well as HTTP and tap_logger package instances. createPost The createPost method creates an HTTP request, setting its URL and enabling you to provide other parameters, such as a time-out and the contentType, and to accept HTTP headers. A call to createPost can be followed by many executePost calls. Only one URL can be active per RESTCallout instance. Calling createPost replaces the URL of a previous createPost call. Here are the signatures for createPost: createPost( url, timeout, id, , rc ); createPost( url, contentType, accept, timeout, id, , rc );

Here are the arguments for createPost: n nvarchar(16384) URL - The web server's URL. n nvarchar(16384) contentType - The type of payload. The default is

application/json; charset=utf-8. n nvarchar(16384) accept - The type of acceptable response. The

default is application/json; charset=utf-8. n int time-out - The time-out in milliseconds of each underlying tkhttp

client request that is executed. This is not an overall cumulative timeout for the POST. n nvarchar(256) id - This is ignored. n nvarchar(256) - This is ignored. n in_out int rc - The input rc variable is updated with the return code.

executePost The executePost method executes an HTTP POST request and updates its output arguments. If the URL and time-out are given, createPost is called with those given arguments. If the signature without the URL is used, the previously created POST request is used. Here are the signatures for executePost: executePost( payload, hstat, executePost( payload, hstat, executePost( payload, hstat, timeout, id,

rc, responseBody ); rc, responseBody, url ); rc, responseBody, url, timeout, );

Here are the arguments for executePost: n nvarchar(67108864) payload - The given body of the POST request. n in_out int hstat - updated with the HTTP status code of POST request

execution. n in_out int rc - The method return code. n in_out nvarchar responseBody - The response from the request. n nvarchar(16384) url - The web server's URL.

180 Chapter 5 / Creating Custom Code with DS2 n int timeout - The time-out in milliseconds. n nvarchar(256) id - This is ignored. n nvarchar(256) - This is ignored.

tap_datetime The package tap_datetime wraps native SAS functions, ing a datetime or date number, as needed, to these functions. n tap_datetime() - Creates a new instance with the date set to January 1,

1960. Note: No local offset can be applied to any numbers that represent SAS dates or datetimes and that are ed to tap_datetime(). Therefore, those numbers have no local offset applied when they are returned from tap_datetime() methods. n tap_datetime(package tap_datetime) - Creates a copy of the given

tap_datetime. n tap_datetime(double sasDatetime) - Creates a new instance that is based

on the given SAS datetime (seconds since January 1, 1960). n tap_datetime(varchar stringRepresentation) - Creates a new instance

from the given string representation. The following formats are ed: o

‘DDMMMYYYY’, for example: ‘15Mar2007’

o

‘DDMMMYYYY:HH:MM:SS’, for example: ‘15Mar2007:15:30:45’

o

‘YYYY-MM-DDTHH:MM:SS’, for example: ‘2007-03-15T15:30:45’

Time zone IDs are standard zone names used by the tz database. For examples, see https://en.wikipedia.org/wiki/ List_of_tz_database_time_zones. n varchar toString() - Returns a string representation of this instance in the

form of 'DDMMMYYYY:HH:MM:SS'. n double toSASDatetime() - Returns the SAS datetime (seconds since

January 1, 1960) corresponding to this instance. n double toSASDate() - Returns the SAS date (days since January 1, 1960)

corresponding to this instance. n fromSASDatetime(double sasDatetime) - Sets time for this instance

based on the given SAS datetime (seconds since January 1, 1960). n fromSASDate(double sasDate) - Sets time for this instance based on the

given SAS date (days since January 1, 1960). n Package tap_datetime s the following native SAS functions, but

unlike their SAS equivalents, these functions take no input arguments. Instead, the values that are returned depend on the date and time that the tap_datetime instance represents. For example, suppose you have an instance of package tap_datetime called “vacation” that is set to the value “12Apr2013”. Then a call to vacation.year() would return the value 2013. For complete descriptions of the native SAS functions, see SAS DS2 Language Reference.

DS2 Programming

181

The advantage to using the tap_* packages is that they correctly call the equivalent SAS methods. Some of the following SAS methods require a SAS date, and some require a SAS datetime. o

int year()

o

int month()

o

int day()

o

int hour()

o

int minute()

o

int second()

o

int weekday()

o

int qtr()

o

double timepart()

o

double datepart()

tap_datetime_utilities The package tap_datetime_utilities contains logically static functions that construct tap_datetime instances, or that operate on more than one tap_datetime instance. n tap_datetime_utilities() - Constructs a new instance. n package tap_datetime datetime(), package tap_datetime today(),

package tap_datetime date() - These methods are equivalent. They return a tap_datetime instance with the time set to current time. n package tap_datetime dhms(package tap_datetime dt, int hours, int

minutes, int seconds) - Returns a new tap_datetime instance that is equal to the given tap_datetime argument, with hours, minutes, and seconds reset to the given values. This is equivalent to the SAS function dhms(). n package tap_datetime mdy(int month, int day, int year) - Returns a

tap_datetime instance that is constructed from the given values. This is equivalent to the SAS function mdy(). n package tap_datetime yyq(int year, int quarter) - Returns a tap_datetime

instance that is constructed from the given values. This is equivalent to the SAS function yyq(). n int datdif(package tap_datetime dt1, package tap_datetime dt2, varchar

basis) - Returns the difference between two tap_datetimes in days. This is the equivalent to the SAS function datdif(). n package tap_datetime SASDatetimeToDatetime(double sasDatetime) -

Returns a tap_datetime instance that is constructed from the given SAS datetime (seconds since January 1, 1960). n package tap_datetime SASDateToDatetime(double sasDate) - Returns a

tap_datetime instance that is constructed from the given SAS date (days since January 1, 1960).

Sample Package sas_activity_tests This is a sample package that can be used for validation and testing. Here are the available methods:

182 Chapter 5 / Creating Custom Code with DS2 echo_string Signature - (varchar(32767) in_string, in_out varchar out_string) Description - Echoes the input string to the output string. echo_int Signature - (int in_int, in_out int out_int) Description - Echoes the input int to the output int. echo_float Signature -(double in_float, in_out double out_float) Description - Echoes the input float to the output float. echo_boolean Signature - (int in_boolean, in_out int out_boolean) Description - Echoes the input Boolean to the output Boolean. echo_datetime Signature - (double in_datetime, in_out double out_datetime) Description - Echoes the input datetime to the output datetime. echo_scalars Signature - (varchar(32767) in_string, int in_int, double in_float, int in_boolean, double in_datetime, in_out varchar out_string, in_out int out_int, in_out double out_float, in_out int out_boolean, in_out double out_datetime) Description - Echoes the input values to the output values. echo_array Signature - (varchar(32767) in_array, in_out varchar out_array) Description - Echoes the input array to the output array. echo_table Signature - (varchar(32767) in_table, in_out varchar out_table) Description - Echoes the input table to the output table. variable_test Signature - (varchar(32767) in_string, bigint in_int, double in_float, int in_boolean, double in_datetime, varchar(32767) in_array, varchar(32767) in_table, in_out varchar out_string, in_out bigint out_int, in_out double out_float, in_out int out_boolean, in_out double out_datetime, in_out varchar out_array, in_out varchar out_table) Description - Edits each of the input values and sets them in the output values. n out_string - The result of reversing in_string. For example, “abc”

becomes “cba.” n out_int - The result of in_int + 2. n out_float - The result of in_float + 1.11. n out_boolean - The negation of in_boolean - true = false and false =

true. n out_datetime - The result of out_datetime + 1 day. n out_array - The reverse array order of in_array - String1, String2,

String3 becomes String3, String2, String1.

DS2 Programming

183

n out_table - The input table with the row order reversed, 100 added to

each column of type int, 222.222 added to each column of type float, 6 days added to each column of type datetime, the string reverse for each column of type string, and the negation for each column of type Boolean.

Using the tap_table Package decodeJSON and encodeJSON Methods The decodeJSON method first clears the tap_table data, and then initializes the tap_table instance with the given JSON text input argument. The decodeJSON method returns a return code type of int. It has one signature, which has one nvarchar input argument. Here is the method signature: method decodeJSON( nvarchar(67108864) input_table ) returns int;

The decodeJSON method's nvarchar string input argument is expected to contain JSON text, conforming to the following JSON dialect: [ { "metadata": [ { " ": " " }, { " ": " " }, ... { " ": " " } ] }, { "data": [ [ ], [ ], ... [ ] ] } ]

Note: White space is ignored. The following sample table illustrates the dialect: [ { "metadata": [ { "myInt": "integer" }, { "myFloat": "decimal" }, { "myString": "string" }, { "myBoolean": "boolean" }, { "mydatetime": "dateTime" } ] }, { "data": [ [ 1, 1.1, "first", false, "1960-01-01T00:00:01Z" ], [ 2, 2.2, "second", false, "1960-01-01T00:00:01Z" ], [ 3, null, "third", false, "1960-01-01T00:00:01Z" ] ] } ]

A null table is encoded as simply "null." A table with no rows has an empty data array. The encodeJSON method returns a nvarchar string consisting of the tap_table instance formatted into JSON text. The encodeJSON method has two signatures, one without any input arguments, and the other with three: encodeJSON( int dblWidth, int dblPrecisn, varchar(128) dblFmtSpecifier ) returns nvarchar;

The signature without args calls the other using 0, 15, and "BESTFIT" as its args. Here is an example: method encodeJSON( int dblWidth, int dblPrecisn, varchar(128) dblFmtSpecifier ) returns nvarchar;

184 Chapter 5 / Creating Custom Code with DS2 The implementation of the encodeJSON method signature without input arguments is as follows: method encodeJSON() returns nvarchar; return( encodeJSON( 0, 15, 'BESTFIT' ) ); end;

The encodeJSON method arguments are as follows: n int dblWidth - Specifies the width for all numeric values that are written. The

value represents the maximum width for SAS formatting, and the minimum width for printf formatting. The values are left-justified. Note: Additional details for SAS and printf formatting are provided below. n int dblPrecisn - Specifies the precision for all numeric values that are written.

Precision indicates the number of digits that appear after the radix character. n varchar(128) dblFmtSpecifier - Specifies one of the following printf or SAS

format type specifiers. The BESTFIT specifier is the default. Printf type specifiers: BESTFIT (default) This is the default specifier. Format the number using a decimal notation style in the form of [-]dddd.ddd, or scientific notation in the form [-]d.ddde ±dd. The formatting style of depends on the value. BESTFITBIG This is the same as BESTFIT, except that the uppercase “E” is used in place of the lowercase “e”, if scientific notation style is used. DECIMAL Format the number using decimal notation in the form of [-]dddd.dd, using the precision to determine the number of digits after the radix. The radix character does not appear if there are no digits to display after it or if the precision is set to 0. FRACTION Format the fractional part of the double in the form of [-]0.dddd. The digit before the radix character is always 0. INTEGER Format the integer part of the double in the form of [-]dddd. The fractional part of the value is ignored, and no radix character is added to the result. SNOTE Format the number as a scientific notation in the form of [-]d.ddde±dd, using the lowercase 'e' to precede the exponent. SNOTEBIG Format the number as a scientific notation in the form of [-]d.dddE±dd, using the uppercase 'E' to precede the exponent. SAS format type specifiers: SASBEST Conforms to the SAS BESTw. format rules. The value is formatted within the specified width. Decimal notation is produced if possible. Otherwise, scientific notation is produced in the form of [-]ddd.dddE[-]dd. Trailing zeros after the radix character are suppressed.

DS2 Programming

185

SASEW Conforms to the SAS Ew. format rules. The values are formatted within the specified width. Scientific notation is always produced in the form of [-]ddd.dddE±dd. SASEWD The value is formatted with the given width precision. Scientific notation is always produced in the form of [-]ddd.dddE±.dd. SASWD The value is formatted with the given width precision. Scientific notation is always produced in the form of [-]ddd.dddE±.dd.

Accessing Database Tables from a Custom SAS Activity or from a Business Rules Node The preferred vehicle for accessing a database is the General I/O activity. However, there might be times when it is advantageous for custom SAS code to do so. To enable SAS activity or business rule code to read from, or write to, a database, you must first create a federated DSN. Federated DSNs contain a list of standard DSNs, enabling access to more than one data source. By referencing the federated DSN in your connection string, you gain access to all of the catalogs and schemas that are referenced by the contained DSNs. For more information about federated DSNs, see SAS Federation Server 4.1: 's Guide. Note: The default DSN in a federated DSN is the first DSN that is added. When you add a federated DSN through the command line utility, this is the first DSN on the list of DSNs. When adding a federated DSN through the UI, add only the default DSN first. Then, you can edit the newly created federated DSN and add any desired additional DSNs. The default DSN is where DS2 packages are stored. The additional DSNs are used for data access from those DS2 programs. Because DS2 packages are stored in SAS data sets, your federated DSN must include BASE_DSN as well as any additional DSNs that reference the database catalogs, schemas, and tables that you want to access. To create a federated DSN, connect to SAS Federation Server Manager and log on to your federation server definition with a ID that has istrative privileges, and follow these steps: 1

With the Federation Server definition selected, click the Data Source Names tab.

2 From the drop-down list, select New Federated Data Source Name. 3 Enter the name and description for the federated DSN, and click Next. 4

From the drop-down list, select Add Data Source Names.

5 Select the DSNs that you want to connect to with this federated DSN, and

click OK. 6 When you return to the screen, click Next. 7 It is recommended that you keep the default security setting, and click Next.

186 Chapter 5 / Creating Custom Code with DS2 8

When you have reviewed the information about the Summary screen, click Finish.

You can test your federated DSN by modifying the following SAS program: proc ds2 Conn="driver=remts;server=your_server;port=your_port;protocol=bridge; uid=_id;pwd=_;conopts=(DSN=your_federated_dsn)";table _null_; method run(); set AN_EXISTING_DATABASE_CATALOG.SCHEMA.TABLE; put a_column= another_column=; end; endtable; run; quit;

Custom SAS activities are implemented as DS2 packages. To read from a table from within a DS2 method, you must use either the DS2 hash package or the DS2 SQLStmt package. To write to a table from within a DS2 method, use the SQLStmt package. The hash package can be used only for reading. To read using a hash object, use the dataset() method of the DS2 hash object. This method takes an SQL SELECT statement as an argument and populates the hash object with the corresponding result set. method compute(); dcl package hash h(); dcl package hiter hi(h); dcl int rc; h.definekey('clientid'); h.definedata('hhid'); h.definedata('income'); h.dataset( '{select clientid, hhid, income from DSORA.MAFUNC.CUSTOMER1;}'); h.definedone(); rc = hi.first(); do while(rc = 0); …do something with the data… rc = hi.next(); end; end;

The SQLStmt package s SQL syntax similar to that used in JDBC parameterized prepared statements, It also provides control over SQL statement lifetime, enabling more efficient code to be written. The following example illustrates writing five records to a database table called “testdata”: dcl package sqlstmt s('insert into testdata (x, y, z) values (?, ?, ?)', [x y z]); do i = 1 to 5; x = i; y = i*1.1; z = i*10.01; s.execute(); end;

DS2 Programming

187

If you want to access databases from custom DS2 code, the database must first be set up within the SAS Federation Server. In the setup process, a data service is created. Within that data service, there is a catalog name that is used for the service. That is the catalog name that should be used when referencing the database from within the custom DS2 code. The schema name depends on the database. However, it is usually the database schema name. For data sets, it is the schema name that is used when setting up the service in the SAS Federation Server. The table name is the actual name of the table in the database. For more information, see SAS 9.4 DS2 Language Reference.

SAS Decision Services Activities SAS Decision Services provides a rich set of activities for constructing decision flows that automate real-time decisions and actions. Activities perform work actions, such as executing SAS programs on a SAS server, storing and accessing information from a relational database, sending web service requests to external systems, executing business rules, and executing scoring models. If your organization has a special processing need that is not covered by the provided activity set, new activities can be added. This is accomplished by developing custom SAS code and publishing it to the SAS Decision Services environment. The activity publishing step assembles metadata. Metadata is necessary in order for the activity to be recognized by a SAS Decision Services engine and to be rendered and tested in a client environment, such as SAS Customer Intelligence Studio or SAS Enterprise Decision Manager. The interface that is used to publish activities is provided by the SAS solution, such as SAS Customer Intelligence, which in turn makes SAS Decision Services API calls in order to publish a new activity. SAS Decision Services uses the following classifications of configurable activities: n SAS activity n web service activity n general I/O activity

The SAS activity type is used to host score code and business rules. It is also used to extend SAS Decision Services functionality. A SAS activity consists of a SAS program and an activity XML document that describes the activity, the methods that are ed by that activity, and the system resources that are used by that activity. DS2 programming skills are required to develop SAS code that runs as an activity. For assistance with custom activity development or publishing, your on-site SAS personnel.

Tips Improve Hash Performance Hash functions take less time to run when you use smaller hash keys. Minimize the size of the variable that you use for your key in a hash.


Initialize Each DS2 Variable Note: You typically declare a DS2 variable before you initialize it. For more information, see SAS DS2 Language Reference. When you are executing a SAS DATA step, variable values are automatically set to missing in the following circumstances: n before the very first iteration of the DATA step n when the BY group changes, if a BY statement is used n when you change from one data set to another using a SET statement that

lists more than one data set DS2 code does not set variables to null or missing by default when the variables are instantiated. In order to prevent unpredictable results, initialize each DS2 variable before you use it. When you are programming in DS2, unassigned variables are not initialized to missing as they are in a DATA Step. As a best practice, you should explicitly initialize all DS2 variables. Related variables with package scope retain their values across method invocations, unless they are explicitly reinitialized. A package scope variable is a variable that is declared prior to the first method declaration of a DS2 package. Before you can use package scope variables, the variables must be identified and instantiated. A package-scope variable is going to keep its value in memory for as long as that variable is loaded into memory on that JDBC connection. For more information, see “Understand How Global Packages and Local Packages Differ” on page 193. A THIS expression provides an alternate method to simultaneously declare and use a global scalar variable from anywhere within a DS2 program. A THIS expression is used to circumvent the standard variable lookup. In a THIS expression, DS2 searches for a scalar variable declaration of the identifier in global scope and local variables with the same name are overridden. If there is no such declaration, DS2 declares the identifier in global scope with DOUBLE type. Global variables can be referenced by all programming blocks in a DS2 program. For more information about variable declarations in DS2, see SAS DS2 Language Reference.

Convert Strings to Numeric Values When you convert a string to a numeric value, be mindful of the encoding of the string. DS2 first translates the string to an intermediate form before making the conversion to a number. The longer the string, the longer the time it takes to convert it. The following code sample contains examples of efficient conversion of strings to numeric values. dcl char(512) s; dcl nchar(512) ns; dcl double x; s = '12.345'; ns = '12.345'; x = s; x = substr(s,1,16); x = substr(ns,1,16);

/* slow */ /* faster */ /* even faster, avoids transcoding */

DS2 Programming

189

Optimize Code with the in_out Keyword The default parameter ing semantics for DS2 are -by-value. Although using -by-value prevents changes within a method from affecting the parameter outside the method, it incurs a performance cost. -by-value es a copy of the parameter’s value to a method. When ing character parameters, a copy of the character value is made. When the method uses the copy, it ensures that the original value is not modified. To limit the number of copied values, limit the number of parameters and specify the size of the values that you are ing into the method. To prevent values from being copied, use the in_out keyword. The following code sample contains an example of sizing parameter values and an example of preventing values from being copied. method copy_made(char(256) x); ... end; method no_copy(in_out char x); ... end;

When a string value is returned by a method, DS2 creates a temporary string to hold the return value. There is a performance cost to copying the returned value from the temporary string to the target location. To improve performance, provide the target location of the return value with an in_out keyword. The following code sample contains an example of using the in_out parameter. method copy_made() returns char(1024); return 'very long string'; end; method no_copy(in_out char return_val); return_val = 'very long string'; end;

Perform a Computation Once If a computation is repeated multiple times, and each time the same value is computed, perform the computation once and save the computed value. For example, the following code sample performs the computation compute(x) four times. if compute(x) > computed_max then computed_max = compute(x); if compute(x) < computed_min then computed_min = compute(x);

If the compute(x) computation always computes the same value for a given value of x, then modify the code to perform the computation once and save the computed value. computed_x = compute(x); if computed_x > computed_max then computed_max = computed_x; if computed_x < computed_min then computed_min = computed_x;

Move Invariant Computation Out of Loops If a computation inside a loop computes the same value for each iteration, improve performance by moving the computation outside the loop. Compute the

190 Chapter 5 / Creating Custom Code with DS2 value once before the loop begins. Use the computed value in the loop. For example, in the following code sample, compute(x) is evaluated during each iteration of the DO loop. do i = 1 to dim(a); if (compute(x) eq a[i]) then ...; end;

If compute(x) computes the same value for each iteration of the loop, then modify the code to perform the computation one time after it is outside the loop. computed_x = compute(x); do i = 1 to dim(a); if (computed_x eq a[i]) then ...; end;

Obtain a Reproducible Random Number Stream To obtain a reproducible random number stream in DS2, follow the same process that you would in a DATA step: use a constant seed for the random number generator. You can do so in one of two ways: n If you are using a RANUNI function, a constant to the random number

function. n If you are using a RAND function, a constant to the STREAMINIT

function. The following example shows a reproducible random number stream using RANUNI. proc ds2; data _null_; method init(); dcl int i; dcl double r; do i = 1 to 10; r = ranuni(1); put r=; end; end; enddata; run; data _null_; method init(); dcl int i; dcl double r; do i = 1 to 10; r = ranuni(1); put r=; end; end; enddata; run; quit;

Output:

DS2 Programming 1 proc ds2; NOTE: Writing HTML Body file: sashtml.htm 2 data _null_; 3 method init(); 4 dcl int i; 5 dcl double r; 6 7 do i = 1 to 10; 8 r = ranuni(1); 9 put r=; 10 end; 11 end; 12 enddata; 13 run; r=0.88386586448177 r=0.97382110217586 r=0.50758258602581 r=0.88694050721824 r=0.68936349358409 r=0.94325460819527 r=0.92878638301044 r=0.48766398406587 r=0.77988508134149 r=0.87713846680708 NOTE: Execution succeeded. No rows affected. 14 15 data _null_; 16 method init(); 17 dcl int i; 18 dcl double r; 19 20 do i = 1 to 10; 21 r = ranuni(1); 22 put r=; 23 end; 24 end; 25 enddata; 26 run; r=0.88386586448177 r=0.97382110217586 r=0.50758258602581 r=0.88694050721824 r=0.68936349358409 r=0.94325460819527 r=0.92878638301044 r=0.48766398406587 r=0.77988508134149 r=0.87713846680708 NOTE: Execution succeeded. No rows affected. 27 quit; NOTE: PROCEDURE DS2 used (Total process time): real time 4.86 seconds u time 1.49 seconds

191

192 Chapter 5 / Creating Custom Code with DS2 The following example shows a reproducible random number stream using RAND. proc ds2; data _null_; method init(); dcl int i; dcl double r; streaminit(1); do i = 1 to 10; r = rand('uniform'); put r=; end; end; enddata; run; data _null_; method init(); dcl int i; dcl double r; streaminit(1); do i = 1 to 10; r = rand('uniform'); put r=; end; end; enddata; run; quit;

Output: 30 proc ds2; 31 data _null_; 32 method init(); 33 dcl int i; 34 dcl double r; 35 36 streaminit(1); 37 do i = 1 to 10; 38 r = rand('uniform'); 39 put r=; 40 end; 41 end; 42 enddata; 43 run; r=0.88386586448177 r=0.97382110217586 r=0.50758258602581 r=0.88694050721824 r=0.68936349358409 r=0.94325460819527 r=0.92878638301044 r=0.48766398406587

DS2 Programming

193

r=0.77988508134149 r=0.87713846680708 NOTE: Execution succeeded. No rows affected. 44 45 data _null_; 46 method init(); 47 dcl int i; 48 dcl double r; 49 50 streaminit(1); 51 do i = 1 to 10; 52 r = rand('uniform'); 53 put r=; 54 end; 55 end; 56 enddata; 57 run; r=0.88386586448177 r=0.97382110217586 r=0.50758258602581 r=0.88694050721824 r=0.68936349358409 r=0.94325460819527 r=0.92878638301044 r=0.48766398406587 r=0.77988508134149 r=0.87713846680708 NOTE: Execution succeeded. No rows affected. 58 quit; NOTE: PROCEDURE DS2 used (Total process time): real time 0.69 seconds u time 0.43 seconds

Understand How Global Packages and Local Packages Differ Global packages and local packages differ in scope and in usage. For package instances that you create in the global scope, you typically create and delete (that is, allocate and free) them once, and use them repeatedly. For package instances that you create in the local scope, you typically create and delete them each time you enter and exit the scope. If you create a package instance that is created and deleted each time a method is called, the resulting create and delete time can incur a performance cost. In the following examples, a hash package is used. Consider also creating a global package of the SQLSTMT package, and preparing an SQL query with parameters. You can then reuse the query, rebinding the parameters for each call. This example creates a hash package that is global. It is created and deleted with the package instance, and it is reused between calls to load_and_clear. /** GLOBAL **/ package mypack; dcl double k d; dcl package hash h([k], [d]);


method load_and_clear(); dcl double i; do k = 1 to 100; d = 2*k; h.add(); end; h.clear(); end; endpackage;

This example creates a hash package that is local. It is created and deleted for each call to load_and_clear /** LOCAL **/ package mypack; dcl double k d; method load_and_clear(); dcl package hash h([k], [d]); dcl double i; do k = 1 to 100; d = 2*k; h.add(); end; h.clear(); end; endpackage;

195

6 Displaying Reports in the Reports Workspace Overview of Displaying Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Customer Intelligence LASR Analytic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Customer Intelligence LASR Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Customer Intelligence Staging Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Configure Autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Overview of Configuring Autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Edit LASR Library Extended Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Modify Autoload Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Set Access Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Test the Autoload Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Schedule Autoload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Extract Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Overview of Extracting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Example Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 The %CISUBJ Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 The %CICOUNT Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 The %CI2LASR Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Schedule the Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Select the SAS Visual Analytics Application Server . . . . . . . . . . . . . . . . . . . . . . . . 212 Reports and Templates in SAS Management Console . . . . . . . . . . . . . . . . . . . . . . Report Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Report Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Extended Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

213 213 214 215

How Responses Are Calculated in Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Overview of Displaying Reports The Reports workspace in SAS Customer Intelligence Studio contains templates for reports that display data from the common data model. SAS LASR Analytic Server is an analytic platform that provides a secure, multi- environment for concurrent access to data that is loaded into memory.

196 Chapter 6 / Displaying Reports in the Reports Workspace Data is extracted from the common data model to a staging library. Autoload loads data from the staging library to the SAS LASR Analytic Server. After the report templates are imported, reports are created from the data on the SAS LASR Analytic Server. For information about accessing SAS Customer Intelligence Studio through SAS Visual Analytics and setting reporting options in business contexts, see SAS Marketing Automation: ’s Guide. For information ing SAS Visual Analytics, see “SAS Visual Analytics” in SAS Marketing Automation: ’s Guide. The following server and libraries are required for displaying reports. SAS LASR Analytic Server Customer Intelligence LASR Analytic Server is the SAS LASR Analytic Server that is installed with SAS Customer Intelligence for use in reporting. You can use this server and the default values, edit the default values, or create your own SAS LASR Analytic Server. For information about Customer Intelligence LASR Analytic Server, see “Customer Intelligence LASR Analytic Server” on page 197. LASR library The autoload process loads data from the data directory into a LASR library. Customer Intelligence LASR Library is installed with SAS Customer Intelligence. You can use this library and the default values, edit the default values, or create your own LASR library. For more information about Customer Intelligence LASR Library, see “Customer Intelligence LASR Library” on page 199. staging library The staging library contains the data that is extracted from the common data model. Customer Intelligence Staging Library is installed with SAS Customer Intelligence. For more information, see “Customer Intelligence Staging Library” on page 200. Customer Intelligence LASR Analytic Server and Customer Intelligence LASR Library are configured to be used with a single common data model. There can be multiple business contexts at your site as long as they share the same common data model. Sites that use more than one common data model for reporting must set up each common data model instance in the same way. Be sure to use a unique namespace for each duplicate setup. Components such as SAS LASR Analytic Servers, LASR libraries, tables, and autoload configurations must be unique for each common data model. To display reports: 1

Configure the autoload process. For more information about configuring autoload, see “Configure Autoload” on page 201.

2 Schedule the autoload process. For more information, see “Schedule

Autoload” on page 206. 3

Create a SAS job that extracts data from the common data model into the staging library. For more information, see “Extract Data” on page 207.

4 Set a schedule for the job to extract data on a regular basis.For more

information, see “Schedule the Job” on page 211. In order for the Reports workspace to be displayed on any device, including mobile devices, SAS Visual Analytics istration and Reporting must be installed at your site. For more information, see SAS Visual Analytics:

Customer Intelligence LASR Analytic Server

197

Installation and Configuration Guide at http://.sas.com/documentation/ onlinedoc/va/index.html. Note: Do not block Reetadata access for the SAS Trusted (for example, sastrust@saspw). The SAS Trusted is a member of the SAS System Services group. To preserve access, grant the Reetadata permission to the SAS System Services group. For more information about SAS Visual Analytics and permissions, see SAS Visual Analytics: istration Guide at http://.sas.com/documentation/solutions/va/index.html.

Customer Intelligence LASR Analytic Server Customer Intelligence LASR Analytic Server is located in the Server Manager plug-in in SAS Management Console. Default values were supplied during SAS Customer Intelligence installation and configuration. To view and edit the default values, select Customer Intelligence LASR Analytic Server, right-click the server connection, and select Properties. Figure 6.1 Connection Properties

The General tab displays the name of the server connection. Figure 6.2

Server Connection Name

The Options tab specifies the port number, and the name of the HighPerformance Analytics environment host. The port number is the T/IP port number that the Customer Intelligence LASR Analytic Server listens on. The High-Performance Analytics environment host is the host path where files that define the cluster are located. This field is applicable to a distributed server only. Use LASR authorization service is selected.

198 Chapter 6 / Displaying Reports in the Reports Workspace Figure 6.3 Server Options

On the Authorization tab, Reetadata, WriteMetadata, and CheckinMetadata permissions are assigned to the Customer Intelligence group. Figure 6.4

Customer Intelligence Permissions

Customer Intelligence LASR Library

199

Customer Intelligence LASR Library The autoload process loads data from the data directory into the Customer Intelligence LASR Library. The Customer Intelligence LASR Library is located in the Libraries folder in the Data Library Manager plug-in in SAS Management Console. Default values were supplied during SAS Customer Intelligence installation. To view and edit the default values, right-click Customer Intelligence LASR Library and select Properties. Figure 6.5

LASR Library Properties

The General tab displays the name and description for the library. Figure 6.6 LASR Library Name and Description

The Options tab specifies the libref and server tag. A server tag is a text string that is associated with a table that is loaded into memory on a Customer Intelligence LASR Analytic Server instance. The server tag is specified in the LIBNAME statement or as a data set option. The server tag and the table name are used together to match the name that is used for tables in the Customer Intelligence LASR Analytic Server. The data provider library is the Customer Intelligence Staging Library that was installed with the product. For more information, see“Customer Intelligence Staging Library” on page 200.

200 Chapter 6 / Displaying Reports in the Reports Workspace Figure 6.7 LASR Library Options

The Data Server tab specifies the database server and connection. The server is the Customer Intelligence LASR Analytic Server that was installed with the product. For more information, see “Customer Intelligence LASR Analytic Server” on page 197. Figure 6.8 LASR Library Data Server

For information about modifying extended attributes to enable autoload, see “Customer Intelligence LASR Library” on page 199.

Customer Intelligence Staging Library Data is extracted from the common data model and loaded into a staging library whose contents are an autoload data directory. The data is autoloaded from the

Configure Autoload

201

data directory into the LASR library. The Customer Intelligence Staging Library is installed with the product. The library is located in the Libraries folder in the Data Library Manager plug-in in SAS Management Console. By default, the following Autoload data directories are created: n Append n Formats n Logs n Unload

If SAS Marketing Automation and SAS Visual Analytics are installed on different SAS server tiers, the data must be on a shared drive that is accessible by autoload. The security permissions for the autoload data directory are determined by your site. The ID that populates this directory must have Write permission. For information about the location of the autoload data directory, see “Modify Autoload Scripts” on page 201.

Configure Autoload Overview of Configuring Autoload After the data is extracted from the common data model and loaded into a staging library, autoload retrieves the data and loads it into the LASR library. Autoload periodically synchronizes in-memory data against tables in a designated directory. To enable autoload to synchronize the extracted data with the content of the LASR library, edit LASR library extended attributes, modify the autoload scripts, and set the correct access permissions. The that executes the autoload script must have a ID in the group that has access permissions. For information about autoload and SAS LASR Analytic Server, see the documentation for SAS LASR Analytic Server at http://.sas.com/ documentation/onlinedoc/lasrserver/index.html.

Edit LASR Library Extended Attributes To enable autoload, edit the values on the Extended Attributes tab of the LASR library. For more information about modifying extended attributes for LASR libraries, see SAS Visual Analytics: istration Guide at http:// .sas.com/documentation/onlinedoc/va/index.html. For information about the location of the Extended Attributes tab, see “Customer Intelligence LASR Library” on page 199.

Modify Autoload Scripts The autoload scripts directory contains autoload, SAS, and scheduling scripts. To modify autoload scripts: 1

Make a copy of the following directory.

202 Chapter 6 / Displaying Reports in the Reports Workspace On UNIX, the directory is / /Applications/ SASVisualAnalytics/VisualAnalytics/VALIBLA. On Windows, the directory is \ \Applications\SASVisualAnalytics \VisualAnalytics\VALIBLA.

For more information about the autoload scripts directory and the configuration directory, see SAS Visual Analytics: istration Guide at http://.sas.com/documentation/onlinedoc/va/index.html. 2 Paste the copy of the directory in the directory for the staging library.

On UNIX, the directory is / /AppData/ SASCustomerIntelligence/MarketingAutomation. On Windows, the directory is \ \AppData \SASCustomerIntelligence\MarketingAutomation. This default location can be modified during configuration or migration. If the SAS Visual Analytics istration and Reporting (VAAR) LASR Analytic Server and the Customer Intelligence LASR Analytic Server are on different machines, copy the directory from the VAAR LASR Analytic Server to the machine where the Customer Intelligence LASR Analytic Server is installed. Do not paste the copy under SASVisualAnalytics. The contents of this location are overwritten with the next update to SAS Visual Analytics. Rename the copied directory. For example, you could name the directory LASRCI. 3

In the new directory, edit AutoLoad.sas. Change the name of the LASR library to Customer Intelligence LASR Library or the LASR library that you created. For more information, see “Overview of Displaying Reports” on page 195. %LET AL_META_LASRLIB=Customer Intelligence LASR Library;

4 Edit the following file.

On Windows, the file is runsas.bat. On UNIX, the file is runsas.sh. Change the pathname for AUTOLOAD_ROOT to the pathname for the new directory. The following example is for the UNIX environment. AUTOLOAD_ROOT="/ /AppData/SASCustomerIntelligence/MarketingAutomation/LASRCI"

The ID that executes runsas.bat or runsas.sh must have access permissions to the LASR library, SAS LASR Analytic Server, and target metadata folder that is specified as the VA.Default.MetadataFolder value on the Extended Attributes tab of the LASR library. For more information, see “Edit LASR Library Extended Attributes” on page 201. 5 Edit the following file.

On UNIX, the file is schedule.sh. Change the pathname for RUNSAS_PATH to include the name of the new directory. The following example is for the UNIX environment: RUNSAS_PATH="/ /AppData/SASCustomerIntelligence/MarketingAutomation/ LASRCI/runsas.sh"

Configure Autoload

203

On Windows, the file is schedule.bat. Add the set RUNSAS_PATH= option to specify the name of the new directory. The following example is for the Windows environment: set RUNSAS_PATH="\ \AppData\SASCustomerIntelligence\MarketingAutomation\ LASRCI\runsas.bat"

By default, the TIME_INTERVAL_MINUTES value is set to 15 minutes. This is the interval at which autoload synchronizes the data. You can edit this value. If the SAS LASR Analytic Server stops, autoload restarts the server and refreshes the data. 6

Edit the following file. On UNIX, the file is unschedule.sh. Change the pathname for RUNSAS_PATH to include the name of the new directory. The following example is for the UNIX environment:

RUNSAS_PATH="/ /AppData/SASCustomerIntelligence/MarketingAutomation/ LASRCI/runsas.sh"

On Windows, the file is unschedule.bat. Add the set RUNSAS_PATH= option to specify the name of the new directory. The following example is for the Windows environment: set RUNSAS_PATH="\ \AppData\SASCustomerIntelligence\MarketingAutomation\ LASRCI\runsas.bat"

If the SAS Visual Analytics istration and Reporting (VAAR) LASR Analytic Server and the Customer Intelligence LASR Analytic Server are on different machines, take the following steps: 1 Copy the SAS High-Performance Analytics include directory to the

directory for the staging library. On UNIX, the directory is / / SASVisualAnalyticsHighPerformanceConfiguration/7.1/Config/ Deployment/Code/Autoload/include.

On Windows, the directory is \ \SASVisualAnalyticsHighPerformanceConfiguration\7.1\Config \Deployment\Code\Autoload\include. 2

Edit the AutoLoad.sas file. Change the pathname for INCLUDELOC to the pathname for the new include directory. The following example is for the UNIX environment:

%LET INCLUDELOC=/ /AppData/SASCustomerIntelligence/MarketingAutomation/include

Set Access Permissions In order for autoload to load the data, you must set the correct access permissions in the properties of the staging library. To set the correct access permissions, take the following steps. 1 On the Folders tab of SAS Management Console, right-click folder that

contains the library and select Properties.

204 Chapter 6 / Displaying Reports in the Reports Workspace Figure 6.9 Library Properties

2

The ID that executes the autoload scripts that access the LASR library metadata must be a member of the Customer Intelligence group. On the Authorization tab of the Properties window, click Add and select the Customer Intelligence group to add to the s and Groups list.

3 In addition to other permissions, the must have ister permission in

order to load a new table for the first time. In the Effective Permissions list, select Grant in the ister row.

Configure Autoload Figure 6.10

205

LASR Library Permissions

Test the Autoload Configuration Test your autoload configuration to that autoload is enabled for the LASR library and that the access permissions are correct. From the directory that you created in “Modify Autoload Scripts” on page 201, execute the following file. On Windows, the file is runsas.bat. On UNIX, the file is runsas.sh. Examine the autoload log file for errors.

206 Chapter 6 / Displaying Reports in the Reports Workspace

Schedule Autoload After you have configured autoload, execute the scheduling script so that your changes take effect. From the directory that you created in “Modify Autoload Scripts” on page 201, execute the following file. On Windows, the file is schedule.bat. On UNIX, the file is schedule.sh. When autoload starts for the first time, the script starts the SAS LASR Analytic Server. To that the server is running, open the Manage Environment page of SAS Visual Analytics . The server status is displayed on the LASR Servers tab. Figure 6.11 Server Status

In some situations, you might need to select a default application server before autoload can start the SAS LASR Analytic Server. For more information, see “Select the SAS Visual Analytics Application Server” on page 212. The table status is displayed on the LASR Tables tab. Figure 6.12 Campaign Status

When you validate autoload for the first time, the list of campaign tables is empty because no data has been extracted.

Extract Data

207

Extract Data Overview of Extracting Data A SAS job extracts the data from the common data model and loads the data into the staging library. The previous version of the data is replaced. The SAS job does the following. n Assigns librefs to the common data model, the LASR library, and the staging

library n Creates a subject table and the associated history, response history,

and treatment history tables from the common data model n Defines additional fields to extract from the common data model n Uses the %CI2LASR macro to extract the data from the common data model.

For information about the contents of the table that contains the extracted data, see “%CI2LASR Output Table Data Dictionary” in SAS Marketing Automation: ’s Guide. When autoload runs, the data is loaded into a LASR library. If any parameters in the job are not valid, the table is not created. Note: If SAS Marketing Automation and SAS Visual Analytics are installed on different SAS server tiers, the extracted data must be on a shared drive that is accessible by autoload. Specify the shared drive information in the VA.Autoload.Location extended attribute for the LASR library. For more information, see “Customer Intelligence Staging Library” on page 200. The job that extracts data from the common data model must run on the SAS server tier where SAS Marketing Automation is installed.

Example Job Here is an example of a SAS job that extracts data from the common data model. The output is located in a file named CAMPAIGN_TREATMENT_DATA. All templates use the contents of this file to generate reports. /************************************************************/ /* Assign SAS libref for the CI Common Data Model Library */ /* -------------------------------------------------------- */ /* Note you can find libname statements in SMC. */ /* Select the library object, right-click, and */ /* select Display LIBNAME Statement. Cut and paste the */ /* libname statement from the dialog box. */ /************************************************************/ LIBNAME CICDM ORACLE PATH=pathname

SCHEMA=myschema

AUTHDOMAIN="mydomain" ;

/************************************************************/ /* Assign SAS libref for library for the extracted data */ /* -------------------------------------------------------- */ /* Library for autoload data directory location. This is */

208 Chapter 6 / Displaying Reports in the Reports Workspace /* the pathname that is specified as the */ /* VA.Autoload.Location extended attribute for the */ /* LASR library. */ /* */ /************************************************************/ LIBNAME BASELIB BASE "pathname"; /************************************************************/ /* In order to extract data from the CI Common Data Model */ /* it is necessary to know what subjects are of interest. */ /* For each subject, it is necessary to know what tables */ /* hold the History, Response History, and */ /* Treatment History data, so it can be summarized. */ /* */ /* Use the %CISUBJ macro to create a Subject Table. Each */ /* call to the %CISUBJ macro adds a subject to the table. */ /* If the table does not exist, it is created. */ /************************************************************/ %ciSubj (subjectTable=WORK.CI_SUBJECT, subject=Customer, _histTable=CI__HISTORY_CUST, response_histTable=CI_RESPONSE_HISTORY_CUST, presentedTreatment_Table=CI_PRESENTED_TREATMENT_CUST); %ciSubj (subjectTable=WORK.CI_SUBJECT, subject=AllAcct, _histTable=CI__HISTORY_ACCT, response_histTable=CI_RESPONSE_HISTORY_ACCT, presentedTreatment_Table=CI_PRESENTED_TREATMENT_ACCT); %ciSubj(subjectTable=WORK.CI_SUBJECT, subject=Household, _histTable=CI__HISTORY_HHD, response_histTable=CI_RESPONSE_HISTORY_HHD, presentedTreatment_Table=CI_PRESENTED_TREATMENT_HHD); /************************************************************/ /* Additional -requested fields. Note that */ /* the syntax for this macro variable consists of items for */ /* a SQL select clause. Each item must have a trailing */ /* comma. */ /* Only tables that are already included in the extract can */ /* be used to request fields that are not included in the */ /* extract. */ /* */ /* Each extracted field is specified in the form: */ /* */ /* AS alias_column_name */ /* 'descriptive label you will see in VA' , */ /* */ /************************************************************/

%let ci__req_fields =

Extract Data

209

ci_campaign.max_budget_offer_amt as campaign_max_offer 'Campaign max budget offer', ci_communication.max_budget_offer_amt as communication_max_offer 'Communication max budget offer', ; /************************************************************/ /* Extract subject data from the common data model and */ /* load it into a staging library. All parameters are */ /* required. */ /************************************************************/ %ci2lasr(subjectTable=work.CI_SUBJECT, CIDMLIB=CICDM, extract_libref=BASELIB, outputTable=CAMPAIGN_TREATMENT_DATA);

The %CISUBJ Macro The %CISUBJ macro builds a table of subjects and related tables for history, response history, and treatment history. /*****************************************************************/ /* NAME: cisubj.sas */ /* VERSION: 6.4 */ /* DESCRIPTION: build table of subjects and related tables for */ /* , response, and treatment history data */ /* */ /* Parameters: */ /* subject= name of subject */ /* _histTable= name of history table */ /* response_histTable= name of response history table */ /* presentedTreatment_Table= name of treatment history table */ /* subjectTable= name of subject table to create/update */ /* (default is WORK.CI_SUBJECT) */ /* */ /* PRODUCT: MA */ /* USAGE: */ /* */ /* %ciSubj ( */ /* subjectTable=WORK.CI_SUBJECT, */ /* subject=Customer, */ /* _histTable=CI__HISTORY_CUST, */ /* response_histTable=CI_RESPONSE_HISTORY_CUST, */ /* presentedTreatment_Table=CI_PRESENTED_TREATMENT_CUST); */ /* */ /* Note that the subject table is consumed by the macros */ /* %CICOUNT and %CI2LASR, using the libref of the common data */ /* model */ /*****************************************************************/


The %CICOUNT Macro The %CICOUNT macro stores the updated counts for each subject in the given subject table from the history, response history, and presented treatment history tables. The %CICOUNT macro is called by the %CI2LASR macro. /*****************************************************************/ /* NAME: cicount.sas */ /* VERSION: 6.4 */ /* DESCRIPTION: accumulate metrics for each subject in the given */ /* subject table from the history, response */ /* history, and presented treatment history tables */ /* for the subject. */ /* */ /* Parameters: */ /* CIDMLIB= libref of common data model */ /* _histTable= name of history table */ /* subjectTable= name of subject table to create/update */ /* (default is WORK.CI_SUBJECT) */ /* resultTable= name of summary data table to create */ /* (default is WORK.CI_CELL_PACKAGE_COUNTS) */ /* */ /* PRODUCT: MA */ /* USAGE: */ /* */ /* %cicount ( */ /* CIDMLib=CICDM, */ /* subjectTable=WORK.CI_SUBJECT, */ /* resultTable=WORK.CI_CELL_PACKAGE_COUNTS); */ /* */ /* Note that the subject table is consumed by the %CI2LASR */ /* macro using the libref of the common data model */ /* */ /*****************************************************************

The %CI2LASR Macro The %CI2LASR macro extracts data from the common data model. /*******************************************************************/ /* NAME: ci2lasr.sas */ /* VERSION: 6.4 */ /* DESCRIPTION: extract data from the common data model and */ /* accumulate counts using %CICOUNT */ /* Parameters: */ /* extract_libref= libref of staging library */ /* CIDMLIB= libref for CDM */ /* subjectTable= name of subject table */ /* outputTable= name of extracted table */ /* PRODUCT: MA */ /* USAGE: */ /* */ /* %ci2lasr( */ /* extract_libref=%(), */

Extract Data

211

/* CIDMLib=%str(), */ /* subjectTable=%str(), */ /* outputTable=%str(), */ /* mode=SIZE | EXTRACT); */ /* */ /*******************************************************************/

mode=EXTRACT is the default. If you specify mode=SIZE, the table is not created. Instead, a data set named WORK.CI_EXTRACT_SIZE is created with the following columns. Row_extract_count

the number of rows that the table would contain.

Column_count

the number of columns in each row.

Row_byte_size

the number of uncompressed bytes in each row.

Total_table_byte_size

the number of uncompressed bytes in the table. This is the result of multiplying row size times row count.

Schedule the Job You use batch scheduling or SAS Management Console to schedule the job to extract data on a regular basis. The extracted data is a snapshot of the contents of the common data model at the time of the extraction. During the process of extracting and loading the data, s are not able to view or create reports. The best time to run this job is when no campaigns are executing and there are no s logged on to SAS Customer Intelligence Studio. Autoload loads the most recently extracted data. The ID that schedules the job must have scheduling permissions. To schedule the job from the command line in the Windows environment, create a BAT file that executes the job. In the following example, the job has been saved in a file named extract.sas. "c:\Program Files\SASHome\SASFoundation\9.4\Sas.exe” -sysin c:\mysasjobs\extract.sas

Enter the following command on the Windows command line. In this example, the BAT file is named sasjobextract.bat. The job is executed every day at 1:00 am. schtasks create /sc DAILY /st 1:00:00 /tn C:\myprogramfiles\sasjobextract.bat

To schedule the job from the command line in the UNIX environment, create a cron table that sets the schedule. In the following example, the job has been saved in a file named extract.sas. The job is executed every day at 1:00 am. 0 1,* * 0-6 sas /mysasjobs/extract.sas

Enter the following command at the UNIX prompt. In the following example, the cron table file is named sasjobextract. crontab sasjobextract

You can also schedule the job through the Schedule Manager plug-in in SAS Management Console. For more information about scheduling and executing SAS jobs, see Scheduling in SAS at http://.sas.com/documentation/onlinedoc/sasmc/index.html.

212 Chapter 6 / Displaying Reports in the Reports Workspace For more information about scheduling tasks in the UNIX and Windows environments, see the documentation for your operating system.

Select the SAS Visual Analytics Application Server Application servers might be installed on different SAS server tiers. In this situation, you must select the SAS Visual Analytics application server as the default before you can start the SAS LASR Analytic Server. To select the application server: 1

Open the Manage Environment page of SAS Visual Analytics .

2

Select File  Preferences. Figure 6.13

3

Manage Environment Preferences

On the Application Server page of the Preferences window, select the application server for SAS Visual Analytics from the Default application server list. Figure 6.14

Select Default Application Server

Reports and Templates in SAS Management Console

213

Reports and Templates in SAS Management Console Report Templates SAS Customer Intelligence Studio provides templates that you can use to display reports in the Reports workspace. During installation, the SAS Package maps the table to an existing table on the SAS LASR Analytic Server. Before you install the report templates, extract data and create the table. For more information, see “Extract Data” on page 207. To install the report templates, take the following steps. 1 Copy the SAS package that contains the report templates from the following

location on the SAS Customer Intelligence Application Server tier to a location on your SAS Management Console client machine. On UNIX, the location of the report templates package is: <SASHome>/SASFoundation/9.4/misc/cicsvr/Config/Deployment/Packages/cireporttemplates.spk

On Windows, the location of the report templates package is: <SASHome>\SASFoundation\9.4\cicsvr\sasmisc\Config\Deployment\Packages\cireporttemplates.spk

SASHome is the directory where SAS is installed on your system. 2

On the Folders tab of SAS Management Console, right-click SAS Folders/ Products/SAS Customer Intelligence/Report Templates and select Import SAS Package.

3

In the Import SAS Package wizard, the location on your SAS Management Console client machine that you specified in Step 1.

4

Follow the rest of the steps in the wizard to import the report templates into the Report Templates folder. On the Tables page of the wizard, specify CAMPAIGN_TREATMENT_DATA as the target table.

Report templates have the following extended attributes: ci.external specifies that the report is not filtered by business context and that the location of the LASR library is not verified. This attribute enables you to generate and view reports against any LASR library that is currently in memory, including LASR libraries that are not part of SAS Customer Intelligence. The report displays data from all the business contexts in the common data model. If both the ci.template and ci.external attributes are specified for a SAS Visual Analytics report, then the ci.external attribute and the ci.template attribute is set for all report instances. ci.template identifies the report document as a report template. All templates are displayed in the Select Template window when you create a new report in SAS Customer Intelligence Studio. This is the only attribute that is assigned

214 Chapter 6 / Displaying Reports in the Reports Workspace to the templates that are provided with SAS Customer Intelligence Studio. The report displays only data from the current business context. This attribute must be added in SAS Management Console to any SAS Visual Analytics report that you want to display in the Reports workspace. For more information, see “Display Extended Attributes” on page 215. If a report template has both the ci.external and the ci.template extended attributes, the report displays data from all of the business contexts in the common data model. However, the report is visible only in the current business context. By default, a report template is visible in all business contexts. To limit the template to a single business context, see “ci.bc.name” in “Report Instances” on page 214.

Report Instances Report instances are located in the SAS Management Console folder that you specify when you save a report in SAS Customer Intelligence Studio. Reports have the following extended attributes. ci.report identifies the file as a report. This extended attribute is required to display the report in the Reports workspace in SAS Customer Intelligence Studio. This attribute is added automatically when the file is saved in SAS Customer Intelligence Studio. ci.bc.name identifies a business context. This extended attribute is required to display the report in the Reports workspace in SAS Customer Intelligence Studio. You cannot specify more than one business context. When this attribute is specified, the report is visible only if the value of the attribute matches the business context for the current . This attribute is added automatically when the report instance is saved in SAS Customer Intelligence Studio. You can use SAS Management Console to add this attribute to any SAS Visual Analytics report that you want to display in the Reports workspace and limit to s of a particular business context. For more information, see “Display Extended Attributes” on page 215. The attribute is required for all report instances. It is optional for report templates. ci.source.template.name specifies the name of the template from which the report was created. The template name is displayed with the report in the Reports workspace in SAS Customer Intelligence Studio. This attribute is added automatically when the file is saved in SAS Customer Intelligence Studio. ci.source.template.path specifies the pathname of the template from which the report was created. This attribute is added automatically when the file is saved in SAS Customer Intelligence Studio.

How Responses Are Calculated in Reports

215

For information about deg reports, see SAS Visual Analytics: ’s Guide at http://.sas.com/documentation/onlinedoc/va/index.html.

Display Extended Attributes To list the extended attributes of a template or a report: 1 Right-click the filename, and select Properties. 2

Select the Extended Attributes tab. Figure 6.15 Example of Extended Attributes for Report

How Responses Are Calculated in Reports Response values for a communication are processed as TOTAL_RESPONSE_CNT, TOTAL_SUCCESSFUL_RESPONSE_CNT, and TOTAL_RESPONSE_VALUE. TOTAL_RESPONSE_CNT is the total number of subjects that responded to the package. This value is a count of subjects such as Customer, Household, or . TOTAL_SUCCESSFUL_RESPONSE_CNT is the total number of responses in which the response type is Converted. TOTAL_RESPONSE_VALUE is the total monetary value of the response. The TOTAL_RESPONSE_CNT value might be deceptively large if there are many possible responses. For example, a single customer might for five responses to a single communication: n Open email n Click link n View product n Add to cart n Purchase

TOTAL_SUCCESSFUL_RESPONSE_CNT depends on how successful responses are defined for the communication. If more than one response is marked as Converted in a Communication node, the number of responses might reflect a higher number than expected.


217

7 Managing Campaign Assets Managing Campaign Assets in SAS Management Console . . . . . . . . . . . . . . . . . 218 Overview of Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Overview of SAS Decision Services Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Location of SAS Customer Intelligence Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Assets and Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Copying and Pasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 Regenerating the SAS Decision Services Metadata Objects . . . . . . . . . . . . . . . . 221 Importing and Exporting SAS Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Data Libraries, Event Variables, and Data Processes . . . . . . . . . . . . . . . . . . . . . . . Data Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites for Defining a Data Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

227 227 227 228 229

Managing Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Overview of Managing Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 About Deploying and Activating Campaigns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 View Campaigns That Are Marked for Deployment . . . . . . . . . . . . . . . . . . . . . . . . 230 Add Remote Deployment Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Enable a Secure Sockets Layer (SSL) Remote Environment . . . . . . . . . . . . . . . 234 Mark Items for Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Understanding Versions and Event Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Understanding Deployment Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 Deploying and Undeploying Selected Campaigns . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Validate Deployed Campaigns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Activating and Deactivating Selected Campaigns . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Import and Deploy Treatment Campaign Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Remove Unused Objects from the Production Repository . . . . . . . . . . . . . . . . . . 246 Migrating Files from a Previous Release of SAS Real-Time Decision Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Migrating Events and Global Variables from SAS Customer Intelligence 5.4 or 5.41 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Exporting and Importing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

218 Chapter 7 / Managing Campaign Assets

Managing Campaign Assets in SAS Management Console Overview of Folders The Folders tab of SAS Management Console displays the folders that contain metadata for SAS Customer Intelligence objects. You can import and export SAS Packages, and copy and paste objects between folders. SAS Customer Intelligence does not use the My Folder or Shared Data folders. Folder permissions are applied to the contents of the folders. If a has permission to edit a folder, then the can edit the contents of the folder and delete an empty folder. If a has permission to view the folder, then the can view the contents of the folder. The cannot add content to the folder, and cannot delete the folder. If a has no access permissions to the folder, then the cannot view or add contents to the folder, and cannot delete the folder. For more information about istrative roles and setting permissions, see the online Help for SAS Management Console. You can create folders, but you cannot rename folders that are used by SAS Customer Intelligence. When you create a folder, it inherits the permissions of the parent folder. You can change the inherited permissions.

Overview of SAS Decision Services Repositories SAS Decision Services repositories contain decision flows that are created by campaigns in SAS Customer Intelligence and their building blocks. These building blocks include events, activities, global variables, and system resources. You specify a repository as a development, testing, or production repository. A repository does not have to be associated with a server; it can be used simply as a storage area for assets. A repository resides in SAS Metadata Repository. However, each Decision Services development, test, and production environment maintains a repository where the assets of the environment are kept. You use the advanced functions in the Decision Services Manager plug-in to SAS Management Console to update, control, or monitor a design-time, test, or production Decision Services environment. The plug-in can be accessed from a Windows client machine that runs SAS Management Console. s of this plug-in are system s, system operators, or performance analysts. The plug-in is divided into two folders: n The SAS Decision Services servers folder provides control of the SAS

Decision Services environments, allowing an to activate and deactivate decision flows and to change the values of global variables. n The Content Repositories folder enables an to manage

SAS Decision Services repositories and their contents.

Managing Campaign Assets in SAS Management Console Figure 7.1

219

Decision Services Manager Plug-in Folders

Icons represent the status of the real-time decision cluster. Here are the icons as well as the type of logical repository that they reference. Indicates that the plug-in is connected to a running SAS Decision Services environment. Indicates that the SAS Decision Services environment is not running. Indicates a production repository. Indicates a test repository. Indicates a development repository. For more information, see “SAS Decision Services Repositories” on page 54.

Location of SAS Customer Intelligence Objects Most SAS Customer Intelligence objects, such as campaigns and campaign definitions, are saved to folders that are specified by the in the business context. Response definitions are stored in a folder in Products\SAS Customer Intelligence. Identifiers and custom detail tags do not appear in the Folders tab in SAS Management Console. Global variables, events, and activities are located in the SAS Decision Services design repository and in the SAS Decision Services engine repository after the campaign is deployed. The location of the SAS Decision Services design repository is determined by the business context settings. When you promote campaigns between SAS Real-Time Decision Manager environments, note the location of the campaign objects in the environment that you are promoting from. For more information, see “Importing and Exporting SAS Packages” on page 222 and“Best Practices for Exporting and Importing Objects” on page 223.

Assets and Permissions The following types of assets are viewable on the Folders tab of SAS Management Console: n System assets are stored in the following folders:

220 Chapter 7 / Managing Campaign Assets o /System/Applications/SAS Customer Intelligence o /System/Applications/SAS Decision Services/Decision

Services 6.4/<SASDSDesignRepository>

Note: There might be multiple SAS Decision Services design repositories. Business context settings determine which design repositories are used. o /System/Applications/SAS Decision Services/Decision

Services 6.4/SASDSEngineRepository

The /System/Applications/SAS Customer Intelligence folder contains SAS Customer Intelligence applications and stored processes. The /System/Applications/SAS Decision Services/Decision Services 6.4/<SASDSDesignRepository> and /System/ Applications/SAS Decision Services/Decision Services 6.4/ SASDSEngineRepository folders contain SAS Decision Services activities, events, flows, global rules, resources, and global variables. n Campaign assets, such as campaign definitions and campaign processes,

are stored in the folder that is assigned to the business context for the campaign. Permissions for these two types of assets are configured differently. Any who has permission to write to system assets can also copy, paste, export, import, and delete the assets. No additional configuration is required. To perform operations on campaign assets, the must be a member of the Customer Intelligence: Usage role. Even with full Write permission, the cannot perform any of these operations without hip in the Customer Intelligence: Usage role. see “istering Group and Role hip” on page 105. If you have Write permission to campaign assets, you can set permissions for an additional or modify the permissions for an existing . Within a business context folder, right-click an asset such as a campaign definition, and select Properties. Modify access permissions on the Authorization tab.

Copying and Pasting You can copy and paste folders and their contents. SAS Real-Time Decision Manager must be installed and configured before you can copy and paste objects. You must also define information maps, business contexts, s, and groups to copy and paste objects that depend on information maps. Use copy and paste, rather than export and import, to move an item to a new business context on the same machine. The codes that are retained depend on the settings for the business context. For information about code settings for a business context, see “Business Contexts” in SAS Real-Time Decision Manager: ’s Guide. To paste an item into a folder, you must have access permissions for the folder. An can temporarily add a to the access control template. The can be removed after the required operation has been completed. To copy an item, right-click the item and select Copy. To paste an item, rightclick the destination and select Paste or Paste Special. Note: You cannot rename objects.

Managing Campaign Assets in SAS Management Console

221

When you select Paste Special, a copy of the item is created. If an item by the same name already exists in the target destination, the item is named Copy of item name. To use Paste Special to include all of the dependencies of a copied object, select the object on the Select Objects to Copy page of the Paste Special wizard. Select Select All to include all of the objects that are listed on the Dependencies tab. If you select individual objects on the Dependencies tab, select the objects under the Copied Objects folder, and then select their dependencies on the Dependencies tab. If you are copying assets such as campaign definitions, use Paste Special to retain all of the dependencies. For example, copies of campaigns and the campaigns that they link to are installed with the same folder structure as the original items. Tags that are no longer in the same environment as the copied treatment are not retained. If you use Paste Special to paste copied items directly into the SAS Folders folder, the source paths are not preserved. Instead, use Export SAS Package and Import SAS Package to preserve source paths in the SAS Folders folder. Copied items retain the permissions of the original items. You can change the permissions of individual objects, such as campaign definitions. Do not change permissions on processes; there might be several campaigns that rely on access to a process. When you copy and paste campaigns and treatments, codes and control group names are retained according to the setting for the business context, and new surrogate keys are generated in the common data model.If you selected the Retain all code values when pasting option in the business context, codes and control group names are retained only when the copied object is pasted within the selected business context.

Regenerating the SAS Decision Services Metadata Objects In order for SAS Real-Time Decision Manager flows to run on the SAS Decision Services server, the server must be populated with the required activities, global variables, custom functions (that is, objects with filenames that begin with _SAS), and utilities code activities (ArrayUtils and TableUtils). If these resources are deleted, you can specify when they are regenerated by entering an option in the following file on every SASServer6 node where SAS Real-Time Decision Manager is deployed. Note: Only utilities code activities and objects with filenames that begin with _SAS are regenerated. Other types of deleted objects cannot be regenerated. On Windows, the file is LevConfig\Web\WebAppServer \SASServer6_cluster_number\conf\wrapper.conf. On UNIX, the file is LevConfig/Web/WebAppServer/ SASServer6_cluster_number/bin/setenv.sh. By default, the amount of time between SAS Decision Services resource population processes is 120 minutes. To change the default time value, enter the following option. -Dcom.sas.analytics.crm.flow.inbound.assets.populate.repeat_interval =

222 Chapter 7 / Managing Campaign Assets By default, the delay between system start-up and the first SAS Decision Services resource population process is 360 seconds. To change the length of the delay, enter the following option. -Dcom.sas.analytics.crm.flow.inbound.assets.populate.initial_interval =

Note: SASServer7 must be running when the objects are ready to be regenerated.

Importing and Exporting SAS Packages The SAS Package Wizard You can use the SAS Package Wizard to export and import collections of objects and their dependencies into subfolders in the SAS Folders tree. To export the contents of a folder, right-click the folder and select Export SAS Package. You can then select the objects for inclusion in the export and save a SAS package file. To import a collection of objects and their dependencies, right-click the destination, select Import SAS Package, and select a SAS package file. To import objects such as campaign processes (including self-learner definitions), decision campaigns, definitions, treatments, decision treatment campaigns, treatment campaign sets, and global rules, navigate to the business context root folder and right-click the subfolder that contains the objects. To import responses and SAS Decision Services objects, right-click the specific folder that contains the objects. Depending on the layout of the assets, it might be easier to import objects in the following order: processes, treatment campaigns, treatment campaign sets, and parent campaigns. The system that you are exporting from and the system that you are importing to must have the same language encoding. For more information, see SAS National Language (NLS): Reference Guide. Imported items retain their original names and overwrite items of the same name that are in the target location. To avoid overwriting existing assets, select New Objects Only in the Import SAS Package wizard. You typically use the SAS Package Wizard in SAS Management Console to promote campaign assets from a design environment to a test environment, or from a test environment to a production environment. (For more information, see “Manually Deploying Campaign Assets in SAS Management Console” on page 237.) However, campaign assets can be promoted from any SAS Decision Services repository to any other SAS Decision Services repository. Make sure that s are logged off from SAS Customer Intelligence Studio before you import or export SAS packages. For more information, see “Managing Sessions” on page 264. For more information about the SAS Package Wizard, see the Help for SAS Management Console.

Permissions A who has View permission can export a SAS package. The import process automatically grants the importing WriteMetadata permission on newly imported objects if the does not already have this permission. To import an item into a folder, you must have access permissions for the folder. An can temporarily add a to the access control template. The can be removed after the required operation has been completed.


223

Select Include access controls in the Import SAS Package wizard only if you want to preserve access controls and the target location contains the same persons, identity groups, and access control templates as the source location. Otherwise, the objects in the package are imported with the default access for the target location.

Best Practices for Exporting and Importing Objects To configure the destination environment, do the following: 1

Create a folder structure in the destination environment that is identical to the folder structure in the source environment.

2

Create an information map in the destination environment that is identical to the information map in the source environment.

3

Create names in the destination environment that are identical to the names in the source environment. Assign the same roles and capabilities to the destination names. names are case-sensitive.

4

Create a repository in the destination environment that has the same name as the repository in the source environment.

5

Create a business context in the destination environment that is identical to the business context in the source environment. The destination business context must have the same name as the source business context.

6

If the objects in the source environment contain dynamic lists, create data libraries in the destination environment that contain the list values. Make sure that the data libraries in the destination environment and the data libraries in the source environment have the same names.

7 You must have Write permission in order to export and import objects. An

import that fails because of permission issues results in a corrupted object. The visual indicator of a corrupted object is a red exclamation point ( ). This object can be deleted only by a with Write permission. For information about exporting objects from the source environment, see “Manually Deploying Campaign Assets in SAS Management Console” on page 237. The exporting and importing process retains all codes, but regenerates surrogate keys. The following codes are retained: n campaign codes n cell codes, including marketing cells n package codes

Campaign Assets in Business Contexts Source and target business contexts can be in different folder locations relative to their root directories. If you export business context assets separately, and you want to keep the relationship between assets, the assets must be imported to the same folder locations relative to each business context root folder. For example, if you want to import a campaign separately from the treatment campaign set that references it, and you want the linkage to be automatically restored, then the

224 Chapter 7 / Managing Campaign Assets campaign should be imported to the same relative folder. If the assets are exported and imported together, they do not have to be imported to the same folder locations relative to each business context. Assets that are not referenced by other assets can be imported into any folder.

Comments Comments are removed from the imported object.

Common Data Model Importing a campaign does not reset the codes in the common data model. However, if you use SAS Management Console to copy and paste a campaign, the following codes are reset in the common data model: n CAMPAIGN_CD n COMMUNICATION_CD n REPLY_CD n MARKETING_CELL_CD n PACKAGE_CD

New surrogate keys are generated in the common data model when you import or copy and paste a campaign. An imported campaign retains its deployment status. If an imported campaign has been marked for deployment, it automatically publishes data to the common data model. If the imported campaign is not marked for deployment, you must use one of the following to methods to publish the data: n mark the campaign for deployment n manually publish the campaign from within SAS Customer Intelligence Studio

Note: You can also set the Automatically publish campaigns on subsequent save in the business context to publish the campaign data every time that the campaign is saved after the first Publish operation. n execute the campaign in the Test interface in SAS Customer Intelligence

Studio For more information, see “Publishing and Executing Campaigns” on page 342 and “Saving, Publishing, and the Common Data Model” on page 373.

Custom Diagram Tools and Custom Nodes Custom diagram tools cannot be imported into a new environment. They must be re-created in the campaign in the destination environment. Custom nodes that are part of a diagram are exported and imported with the campaign.

Definitions If you include dependent objects when you export a campaign, the campaign definition is not exported. If importing a response definition would result in a duplicate channel response code for a specific channel, the channel response code field is empty in the imported definition.


225

When you import a definition, the only business contexts that remain associated with that definition are those business contexts for which you have Write permission.

Decision Treatment Campaigns and Treatment Campaign Sets If decision treatment campaigns and treatment campaign sets are imported, they overwrite existing objects of the same name. All dependencies, such as the connection of decision treatment campaign to treatment campaign sets, are retained. Newer decision treatment campaigns on the target system are included. Therefore, the imported treatment campaign sets contain a union of source system , if they exist on the target system, and newer on the target system. Note: Existing campaigns are not overwritten when a campaign is imported. If a campaign has already been marked for deployment in the previous environment, SAS Real-Time Decision Manager attempts to mark the imported campaign and all its dependencies for deployment in the new environment. Be sure to check the SASCustIntelCore6.4.log file in the \Lev1\Web \Logs\SASServer6_N directory to that the deployment was successful; a warning message does not appear if there was a problem with the deployment during import. A warning message appears in the log if the mark for deployment operation is unsuccessful. You can manually mark the items for deployment in the new environment. You can import the decision treatment campaigns and the treatment campaign sets separately if the treatment campaigns are in the same relative path within the business context folder structure. If you want to overwrite an existing treatment campaign set to use the member list from the exported treatment campaign set instead of the existing member list on the system, you must import the treatment campaigns and treatment campaign sets in the same SAS package.

Events When you import an event directly (that is, apart from a campaign), all identifiers that are not already created are deleted from the event the next time the event is opened. If a campaign that uses the same event is then imported, the new identifiers are retained, new identifier definitions are created, and the event definition is updated with the new identifiers. When you import event variables into SAS Real-Time Decision Manager, the column names in the imported table must match the localized event column names in the interface. For example, in the English locale, the imported event variable table must have the following column names. n Variable Name n Display Name n Description n Type n Identifier n Level n Required


Global Rules Imported global rules will be used by all existing campaigns in the business contexts that share the same common data model.

Identifiers If an identifier that is used in a Start node or a Reply node does not exist on the target system, it is created as when the campaign is imported. Identifiers are references to variables that are used to create campaigns more efficiently. For more information, see “Identifiers” in SAS Real-Time Decision Manager ’s Guide. When an identifier is created during import, the import cludes the following message: The identifier was automatically created as a globally defined identifier. The import cludes a warning message if an identifier of the same name already exists but it of a different data type.

Self-Learner Definitions If you import a self-learner definition from a business context to a business context that uses a different information map, the import process does not remove a data item from the new self-learner definition if the data item has the same ID as the data item in the new information map. Instead, the data item from the target information map is referenced. Data items referenced in the imported self learner definition that are not in the target information map are removed. A warning message appears if the original data item is not available when you open the imported self-learner definition. Note: You can modify the Self Learner Threshold parameter in the autoexec file to specify the minimum number of cases needed to generate a non-random score. The default is 1000 cases.

Treatments When you import treatments along with a campaign, a number in a red disc in the Updates page for the campaign in SAS Customer Intelligence Studio indicates that the imported campaign treatment is not in sync with existing treatments. Select Updates or Rejections to display changed treatments or treatments whose changes have been rejected. Click contents of the Treatments page.

in the toolbar to refresh the

Select a treatment to compare the campaign version of the treatment with the changed version. Campaign Treatment is the version of the treatment that is associated with the campaign. Treatment is the changed version. Click

to accept the changes. Click

to reject the changes.

Note: Changed values in dynamic custom details are not updated. To include the changed values in the treatment, remove the dynamic custom detail and then add it again to the treatment. Imported treatments with attached images must map to treatments in the destination folder. Otherwise, the images are not available to campaigns. If you want to associate an image with a treatment, you can attach an image or provide the URL that contains the image. An attached image comes with a treatment that is exported or imported. The URL that contains the image needs

Data Libraries, Event Variables, and Data Processes

227

to be accessible by the new system if you want to view the image on the new system. Therefore, if you use a URL that points at a local file, then you must make sure that the same URL is valid on the new system. If the URL is not valid, you might need to copy the image and paste it in the same location on the new system.

Memory Size If you import a large package, you might need to increase memory size. In the sasmc.ini file, modify the following code. JavaArgs_1=-Xmx2048m

Data Libraries, Event Variables, and Data Processes Data Libraries The Data Library Manager in SAS Management Console lists the data libraries that can be selected for an event input variable of type Data Grid or for a data process. The list of data libraries that are available for selection by a data process is based on the JDBC library resources that are defined in the SAS Decision Services repository. A data process and an event input variable of type Data Grid can reference the same data library. Figure 7.2 Data Library Manager

Event Variables An event can have an input variable of type Data Grid. In SAS Customer Intelligence Studio, the location of input data grids that can be used in the Test interface is specified in the Data Options on the Settings tab for the business context, as the Decision test data grid input library selection. The

228 Chapter 7 / Managing Campaign Assets data grid for the event input variable is selected on the Test tab of a diagram in Test Mode. An event can also have an output variable of type Data Grid. In SAS Customer Intelligence Studio, the location of output data grids that can be used in the Test interface is specified in the Data Options on the Settings tab for the business context as the Decision test data grid output library selection. Input and output library locations that can be used only in the SAS Customer Intelligence Studio Test interface are selected from a list that is provided by the Data Library Manager in SAS Management Console. Figure 7.3 Data Options

Data Processes Overview of Data Processes Data processes are used to communicate with the database directly from a campaign. Your data sources can be database management systems or SAS data sets. SAS data sets can be used by SAS Decision Services to hold data, as well as DS2 activity code and score code. When you use a SAS process to access data that is held in SAS data sets, you must configure a DSN in SAS Federation Server that uses the Base driver, and then use this DSN (or a federated DSN that includes this DSN) in the resource definition. For more information, see SAS Federation Server Manager: 's Guide. Note: SAS data sets can be used only at development time. Do not use SAS data sets in production. When you use a data process, a single row transaction is initiated every time that a campaign is executed. Before using data processes, make sure that the database is appropriately tuned and adequate for row-level transactions. The database must also the latency requirements of the campaign. If low latency is required, it is recommended that you use a data process that does not require a data table . SAS Customer Intelligence Studio accesses the data through the SAS Management Console metadata. However, this metadata is not used at run time. At run time the data is accessed using the database location that is defined in the General I/O resource (that is, the metadata object that is in your SASDSDesignRepository or SASDSEngineRepository).

Managing Deployments

229

For information about defining a data process in SAS Customer Intelligence Studio, see “Defining the Components of Campaigns” in SAS Real-Time Decision Manager: ’s Guide.

Prerequisites for Defining a Data Process Before a data process can be used in SAS Customer Intelligence, you must create a data library, a JDBC Connection system resource, and a Library system resource. Both the data library and the Library system resource must have the same name. To create a library, right-click the Libraries folder in the Data Library Manager on the Plug-ins tab of SAS Management Console, and select New Library. JDBC Connection system resources are used by both SAS activities that execute DS2 programs and by data processes that access database records. For data processes, multiple database server URLs can be specified, in a single system resource, in order to database clusters that do not have serverside load balancing. Each space-separated URL references one node of a clustered database environment. To create a JDBC Connection system resource, follow the instructions in“Specify a New System Resource as a JDBC Connection” on page 123. To connect to SAS DATA sets and to execute DS2 SAS activities, a JDBC Connection system resource must be configured to connect to one or more SAS Federation Servers. The JDBC Connection system resource named $SAS_ACTIVITY_RESOURCE is configured for this purpose. For more information, see “JDBC Connection System Resources” on page 120. Your SAS Decision Services repository can contain zero or more Library system resources. You must create a library system resource for each alias that you want to define to reference a database schema. For information about creating a library system resource,see “Library Resources” on page 127.

Managing Deployments Overview of Managing Deployments In the Deployments category in the istration workspace, you can deploy campaigns to the SAS Decision Services Engine Server, remove campaigns from deployment, edit remote deployments, activate campaigns as decision flows, remove unused objects from the production repository, and add and remove deployment environments. You can compare the list of campaigns that are marked for deployment with the campaigns that have been deployed to the production repository. For information ing SAS Management Console to manage deployments, see “Manually Deploying Campaign Assets in SAS Management Console” on page 237.

230 Chapter 7 / Managing Campaign Assets Figure 7.4

Deployments Category

In order to display and use all of the features of the Deployments category, you must have the following capabilities. n Allow mark campaign for deployment n Manage promotion n Allow manage remote deployment environments n Allow deploy and undeploy campaigns n Allow activate and deactivate campaigns n Allow repository maintenance

For more information, see “Predefined Roles for SAS Customer Intelligence” on page 95.

About Deploying and Activating Campaigns Deploying a campaign copies events, flows, activities, and global variables from the local SAS Decision Services design repository to a local or remote SAS Decision Services Engine Repository. This process also automatically updates preinstalled activities. Activating a campaign sets the flow as active in SAS Decision Services Engine Repository, places the flow in the JVM run-time cache in the SAS Decision Services Engine, and starts serving requests from the SAS Decision Services Engine. Before activating a campaign, it is recommended that you activate all subdiagrams that are being used by the campaign. Synchronization of the repository occurs whenever a flow is activated or deactivated. You can also synchronize the system by selecting Synchronize with Repository from the Decision Services Manager plug-in for SAS Management Console. It is possible to automate the activation process. Activation can be performed through SAS Customer Intelligence Studio, SAS Management Console, BatchActivator, Hyperic plug-in, or the SAS Decision Services istration API. For batch activation, it is preferred that the SAS Decision Services istration API be used. For more information, see Appendix 7, “SAS Decision Services istration,” on page 443

View Campaigns That Are Marked for Deployment Select a business context to display the campaigns that are marked for deployment for that business context. Select a deployment environment to display the deployment status of items in that environment.

Managing Deployments Figure 7.5

231

Business Context and Deployment Environment

The list displays the campaigns that are currently marked for deployment or were modified after being marked for deployment, along with the treatment campaigns and treatment campaign sets that are referenced by the displayed campaigns. Figure 7.6 Deployment Status List

A deployment environment is a SAS Decision Services Engine Server where campaigns are deployed. To view the available deployment environments, select Manage Remote Deployment Environments.

232 Chapter 7 / Managing Campaign Assets Figure 7.7

Manage Remote Deployment Environments

The list of remote deployment environments is displayed. Figure 7.8 Manage Remote Deployment Environments

To add or remove deployment environments from the list, you must have Edit permission for the business context. For information ing command-line scripts to manage remote deployments, see “Use the Launcher to Complete Tasks” on page 401. Note: Single sign-on is not ed for remote deployment environments.

Add Remote Deployment Environments As part of the deployment process, the published SAS Customer Intelligence objects from the development environment are copied over to the common data model in the remote deployment environment (that is, the execution environment). To do this, the development environment requires a reference to the data library in the remote deployment environment. To add this library reference: 1 Define a library in the Data Library Manager plug-in in SAS Management

Console on the local system. To define a library: a

In SAS Management Console, right-click the library name in the Data Library Manager plug-in and select Display LIBNAME Statement.


233

Figure 7.9 Display LIBNAME Statement

b

Note the libref value in the LIBNAME statement. You will use the libref value when you add a remote deployment environment and when you create the cata SAS Federation Server. Figure 7.10

Libref Value “CIORA” in LIBNAME Statement

Note: Schema names are case-sensitive. For SQL Server, the libref value should be the database name. 2

In SAS Customer Intelligence Studio, click environment.

to add a deployment

234 Chapter 7 / Managing Campaign Assets Figure 7.11 Add Environment

3

Specify the name, host server, and other information. By default, the remote server HTTP connection is to an external URL. If the remote server connects through an external URL, but the local server connects through an internal URL, the connection fails. In this case, select Use Internal URLs for the remote server. If you do not select a value for Authentication domain, the is prompted for a ID and . In order to log on to the remote deployment environment, the must have the role of SAS Decision Services . The common data model contains the data from published campaigns. Select a libref for the location of the common data model from the Common data model libref list. If you do not select a common data model libref or if you select the same libref as the libref for the current business context, campaigns are not published to the remote environment.

4

Click Settings to ensure that you have added a valid deployment environment.

5 Select a deployment environment and click

to change the settings.

For more information about SAS Decision Services Engine Servers, see “Production Environment” on page 50.

Enable a Secure Sockets Layer (SSL) Remote Environment To enable a Secure Sockets Layer (SSL) remote environment to be accessible from SAS Customer Intelligence Studio: 1

On the SSL server machine, issue the following command to retrieve the SSL server public key:


235

openssl s_client -connect SSL server name:port number

2

Copy the lines from the generated output, beginning with BEGIN_CERTIFICATE and ending with END_CERTIFICATE. Paste the copied output in a folder on the middle tier. For example, the folder pathname could be \public\certificate.

3 From the location on the middle tier where JRE is installed, issue the

following command: ./keytool -import -alias SSL server name -keystore "$JRE_HOME/lib/security/cacerts" -file \public\certificate

4 Restart the middle-tier server.

Mark Items for Deployment To mark a campaign or a treatment campaign set for deployment, click SAS Customer Intelligence Studio toolbar.

in the

If the campaigns are valid, the SAS Decision Services flow objects are generated on the SAS Decision Services design-time server and the campaign metadata is published to the common data model. You cannot mark a campaign for deployment if the campaign end date is in the past, or if the Reply node or standard reply has been assigned a treatment whose expiration date is in the past. All campaigns should be validated, tested, and approved before being marked for deployment. TIP It is a best practice to mark campaigns for deployment before you deploy treatment campaign sets so that the campaigns are already available when you deploy a treatment campaign set.

You can refresh data and delete old records after a campaign has been marked for deployment and published to the common data model. Create a new version of the campaign and mark the new version for deployment. To mark items for deployment in SAS Management Console, click the Folders tab. In the folder that contains the SAS Real-Time Decision Manager objects, right-click the objects and select Mark for Deployment. You can mark multiple campaigns, decision treatment campaigns, and treatment campaign sets for deployment at the same time. For information ing command-line scripts to mark campaigns for deployment, see “Use the Launcher to Complete Tasks” on page 401.

Understanding Versions and Event Names The Version column displays the version of the campaign in SAS Customer Intelligence Studio and the number of times that the version has been marked for deployment. For example, 2.4 indicates that version 2 of the campaign has been marked for deployment four times. A new campaign would have a version of 1.0. The Deployed Version column in the Deployment category interface displays the SAS Customer Intelligence Studio version and the version of the

236 Chapter 7 / Managing Campaign Assets campaign when it was last deployed. For example, 1.2 in the Deployed Version column indicates that the campaign was deployed after the second time it was marked for deployment. Even though the campaign was marked for deployment twice, the campaign might not have been deployed after it was marked for deployment the first time. The Event Name column displays the events that are associated with the campaign, treatment campaign, or treatment campaign set. For information about versions and events in SAS Customer Intelligence Studio, see SAS Real-Time Decision Manager: ’s Guide.

Understanding Deployment Status Note: If you update the reporting version of a campaign in the Status and Versions page, the campaign will not appear in the Deployments table until that version of the campaign has been marked for deployment. For more information, see “Status and Versions” in SAS Real-Time Decision Manager: ’s Guide. The following table lists and describes the deployment statuses for decision treatment campaigns and treatment campaign sets. Status

Description

Deployed

An object has a status of Deployed only when the latest version of the object is deployed to the engine and any children objects also have a status of Deployed. For example, a parent campaign is Deployed when the current version is deployed to the engine and all the treatment campaign sets that the parent campaign references have a Deployed status. A treatment campaign set is Deployed when its current version is deployed to the engine and all the treatment campaigns that it references have a status of Deployed. Note: If a decision treatment campaign that is associated with a campaign is edited after a campaign is deployed, the status of the deployed campaign becomes Partially deployed.

Deg

Parent campaigns, treatment campaign sets, and treatment campaigns have a Deg status if the object has been edited since the last time it was marked for deployment.

Not deployed

An object is Not deployed when the current version of the object has not been deployed to the engine and all of the object's children have a Deg or Not deployed status.


237

Status

Description

Partially deployed (treatment campaign sets and parent campaigns only)

Partially deployed indicates that there is a combination of deployment statuses for the object and the object’s children. For example, a parent campaign has a Partially deployed status if its current version is deployed to the engine and at least one of the treatment campaign sets that it references has a Deg or Not deployed status. A treatment campaign set has a status of Partially deployed occurs if its current version has not been deployed to the engine and a current version of one of the treatment campaigns that it references has a Deployed status.

For information about the life cycle of a campaign, see “Life Cycle of a Decision Campaign” on page 52.

Deploying and Undeploying Selected Campaigns Deploy and Undeploy Selected Campaigns in SAS Customer Intelligence Studio Select one or more campaigns, and click Deploy to deploy the campaigns. Dependent events, global variables, activities, treatment campaign sets, and decision treatment campaigns are also deployed. When you deploy campaigns, the campaign and its dependent objects are copied to the engine repository. Click Undeploy to remove inactive campaigns or treatment campaign sets from deployment. Only the selected items are removed from deployment. When you undeploy a treatment campaign set or decision treatment campaign, events that are associated with the treatment campaign set or decision treatment campaign are removed. Events that are associated with campaigns that include the treatment campaign set are not removed.

Manually Deploying Campaign Assets in SAS Management Console You can use SAS Management Console to manually deploy, or promote, campaign assets to a SAS Decision Services repository. Promotion consists of exporting assets from one repository and importing them into another repository. The campaign assets that you can export are activities, flows, global rules, variables, and events. Note: During day-to-day operations, you typically need to promote only flows and variables. You typically promote a flow from a development environment to a test environment, or from a test environment to a production environment. (For more information, see “Life Cycle of a Decision Campaign” on page 52.) However, flows and other objects can be promoted from any SAS Decision Services repository to any other SAS Decision Services repository. For more information about repositories, see “Overview of SAS Decision Services Repositories” on page 218.

238 Chapter 7 / Managing Campaign Assets Here are the rules for promoting campaign assets: n As a general rule, resources should not be promoted. System resources

define how SAS Decision Services interacts with external systems. Because those systems and interactions are different in a production environment than in a development environment, promoting a resource can have undesirable consequences. n Activity promotion is necessary only after publishing a new or modified

SAS activity. When an activity is published, the source code for the activity is stored with the activity metadata. When a SAS activity is promoted, its source code is automatically promoted along with it. Be sure to promote a new or modified activity before deploying any flows that use it. n Do not overwrite an active flow. If a flow, or other SAS Decision Services

object, is promoted to an environment where an object with the same name and type already exists, the object in the target environment can be overwritten. When you overwrite an active flow, the engine is not notified that the flow changed in the repository. Instead of overwriting the flow, deactivate the flow in the target system, promote it, and activate it. These steps cause the engine to load the updated flow. Note that when a flow is promoted, its state is automatically set to inactive. SAS Decision Services includes a rich set of activities. If your organization develops a new activity that extends SAS Decision Services functionality, that activity must be promoted to each development, test, or production environment that uses the activity. Any system resources that are referenced by the new activity must also be created in these environments before flows that use the activity are activated. Before promoting any updated activity where a method signature was modified, be sure to deactivate and delete all flows in the target repository that reference the original activity. Failure to do so might yield run-time errors or unexpected results. Before you promote a new event, make sure that an event with the same name does note exist in the engine. If you overwrite an existing event, then any active flows or sub-flows that use the event might fail. To update an existing event, make sure that all flows using the original version of the event are deactivated first. The following example illustrates the promotion of an activity from a development repository to a production repository. Although both repositories are contained by the same folder in the example, this condition is not required. 1

Launch SAS Management Console and click the Folders tab. CAUTION! The Folder view in SAS Management Console does not restrict the locations to which assets can be exported. However, to avoid unpredictable results, always export from an individual asset.

2

Expand the System and Applications folders.

3

Expand the SAS Decision Services and Decision Services 6.4 folders.

4 Select SASDSDesignRepository. 5

Right-click the asset that you want to promote, and select Export SAS Package (note the previous caution).


6

239

Enter a package name, and click Next.

7 Select the assets that you want to promote. A convenient way to select only

the boxes that you want is to select Clear All. Then select each XML file that you want to promote. Click Next.

8

the package name, location, and contents, and click Next. The flow has now been successfully exported from the development environment and saved in the package file called YourPackage.spk. The

240 Chapter 7 / Managing Campaign Assets second part of the promotion process is to import the asset into the production environment. 9

Right-click the repository folder of the repository that you want to promote the asset to, and select Import SAS Package. CAUTION! The Folder view in SAS Management Console does not restrict the locations to which assets can be imported. To avoid unpredictable results, always import to a repository folder.

10 Navigate to your package name. If you import directly after exporting, then

the package name is automatically supplied. To avoid overwriting existing artifacts, select New Objects Only. Click Next. 11 that a check mark exists beside the XML file of each asset that you

selected. Click Next.


241

12 that the summary is correct and click Next. 13 Click Finish.

The promotion operation copies the asset without removing the asset from the source repository. The asset has been successfully promoted from the development to the production repositories as shown below.


You can further that the promotion process was successful by viewing the contents of the XML file after promotion. 1

Click YourProductionRepository folder so that it appears in the righthand pane.

2

Right-click the asset that you promoted and select View SAS Decision Services content.

If the XML content can be viewed, then the promotion was successful.

Repeat the promotion steps for each asset to be promoted.


243

For more information about SAS Promotion Tools, see http://.sas.com/ documentation/cdl/en/bisag/68240/HTML/default/ viewer.htm#p04l8c3fo8tpyhn103dps7pxvru2.htm.

Validate Deployed Campaigns Select one or more campaigns with the status of Deployed, and then click Validate to validate the campaigns. SAS Real-Time Decision Manager checks to that the flow is valid, and that any activities or resources that are used by the flow are available and valid. This validation enables you to see any failures (such as missing resources, activities, or events that are associated with subflows) that might occur during deployment activation, so that you can fix them before activating the deployment. This validation process uses the same validate functionality within a campaign that occurs when the flow is activated in the engine. For more information, see “Activating and Deactivating Selected Campaigns” on page 243. Note: The Validate button is disabled if a deployed campaign is already active in the engine.

Activating and Deactivating Selected Campaigns About Activating and Deactivating Campaigns When a campaign is activated, the SAS Decision Services Engine loads it, making the campaign ready to process events. When a campaign is deactivated, the engine unloads it, making the campaign no longer ready to process events. When a campaign is deactivated, the engine unloads it, making it no longer ready to process events. When the engine receives an event for which there is no active flow, it returns a no flow message. A flow is the only object that can be activated or deactivated. All other objects are used by flows, directly or indirectly, and are loaded when they are referenced by an active flow. When loaded, flows and other objects are synchronized across the machines in the SAS Decision Services cluster and cached in memory for maximum performance. Each flow is bound to an event, which specifies the type of request a flow processes. Many different flows that reference the same event might exist in a repository, but only one of those flows can be active at any given time. For example, suppose flows A and B reference event X, and suppose A is active. Whenever event X is received, it is routed to flow A. If you activate flow B, SAS Decision Services automatically deactivates flow A. Now, whenever event X is received, it is routed to flow B. It is not necessary to activate or deactivate flows in the development environment. When a flow test is run using the SAS Customer Intelligence Test interface, SAS Decision Services automatically loads, tests, and unloads the appropriate flow. Because the development environment is not connected to channels, the active or inactive states of the flows there are irrelevant.


Activate and Deactivate Selected Campaigns in SAS Customer Intelligence Note: It is recommended that you validate a campaign before you activate it to ensure that all dependent metadata objects (except subdiagrams) are available in the environment. For more information, see “Validate Deployed Campaigns” on page 243. Select one or more campaigns, and click Activate to activate the campaigns. When you activate a campaign, you activate the SAS Decision Services flow that was generated when the campaign was marked for deployment. Click Deactivate to deactivate selected campaigns. Note: In SAS Customer Intelligence Studio, you can activate only the latest version of a campaign. To activate a previous version of a campaign, go to SAS Management Console, right-click the campaign in the SASDSEngineRepository folder on the Plug-ins tab, and then select Activate. For more information, see “Activate and Deactivate Selected Campaigns in SAS Management Console” on page 244. In order to be able to activate and deactivate decision flows, you must have the Decision Services: istration role. Note: After campaigns are activated as decision flows, the flows are placed in the run-time cache for JVM in SASServer7. If the flows are not being updated, use the logs for the cache for SASServer7 to troubleshoot the problem. For more information, see “Logs for Troubleshooting” on page 322.

Activate and Deactivate Selected Campaigns in SAS Management Console To activate a flow in SAS Management Console: 1 Launch SAS Management Console. 2

Expand Decision Services Manager and the SAS Decision Services servers folder.

3 Expand the SAS Decision Services system that contains the flow that you

want to activate. In the example below, SASDSEngineServer represents a running engine that is deployed within a cluster. The green check mark indicates that the plug-in has been successfully connected to the engine. 4 Expand the repository (SASDSEngineRepository in the following example)

and click Decision Flows.


5

In the right-hand pane, right-click a flow and select Activate.

When a flow has been successfully activated, the following dialog boxes appear:

245

246 Chapter 7 / Managing Campaign Assets The first dialog box indicates that the flow was successfully marked as active in the repository. The second dialog box indicates the flow was successfully activated in the running system and is now ready to process events. The flow status changes from inactive to active, as shown below.

To deactivate a flow in SAS Management Console, follow the previous steps in order to view the list of flows. Then right-click an active flow, and select Deactivate, as shown below.

Flows can be activated or deactivated in a system that is offline, to indicate which flows to load during system start-up. In this case, the green check mark on the engine icon is replaced by a red X, indicating the engine is not running. Upon successful activation, only the dialog box indicating successful activation or deactivation in the repository appears.

Import and Deploy Treatment Campaign Sets You can use SAS Integration Utilities to import treatment campaign sets separately from importing the member campaigns. If a treatment campaign set with missing campaigns is opened in SAS Customer Intelligence Studio, the is prompted to make one of the following choices. n Save the treatment campaign set, thereby losing the references to missing

member campaigns. n Close the treatment campaign set.

If the closes the treatment campaign set without saving, the can import the missing campaigns. Alternatively, the can remove the existing references to member campaigns and add new decision treatment campaigns to the treatment campaign set.

Remove Unused Objects from the Production Repository You can remove orphaned decision treatment campaigns and other unused objects from the production repository. Click Maintenance to select the objects to remove. istration tasks might be slower if you do not remove unused objects from the production repository.

Migrating Files from a Previous Release of SAS Real-Time Decision Manager Figure 7.12

247

Select Objects to Remove

For information ing command-line scripts to remove unused objects, see “Clean Up Production Repository” on page 399.

Migrating Files from a Previous Release of SAS Real-Time Decision Manager Migrating Events and Global Variables from SAS Customer Intelligence 5.4 or 5.41 In SAS Real-Time Decision Manager 6.x, events and global variable definitions are stored in a single location: a SAS Decision Services repository within the SAS Metadata Repository. During migration from SAS Customer Intelligence 5.4 or 5.4.1, the event or global variable definition is created in the SAS Decision Services repository. The display and physical names for the event or global variable definition are not modified during migration. For information about migrating files from a previous release of SAS Real-Time Decision Manager, see SAS Real-Time Decision Manager: ’s Guide.

Exporting and Importing Files When you are moving events and global variables from the SAS Customer Intelligence 5.4 or 5.4.1 SAS Metadata Repository to the SAS Decision Services repository for SAS Real-Time Decision Manager 6.x , export only the Customer Intelligence copy of the object and its dependencies as a SAS package. Then import the package to a directory under the business context root directory. The import code creates the SAS Decision Services event, global variable, or activity, and deletes the Customer Intelligence object. When you move events and global variables from a 6.x SAS Metadata Repository to the 6.x SAS Decision Services

248 Chapter 7 / Managing Campaign Assets repository, you export the SAS Decision Services event or global variable object. On import, the objects are imported into a SAS Decision Services repository. In SAS Real-Time Decision Manager 5.4, the activity code for SAS processes and models was stored as SAS DATA step code in a folder. In 5.41 and later, the activity code uses DS2 code that is embedded within the activity stored in a SAS Decision Services repository. As a result, you must save the SAS process and model definition from the 5.4 release to ensure that the activity is updated to include the DS2 code. If you are migrating from the 5.4 release to a 5.41 release or later, it recommended that you manually convert the SAS DATA step code to DS2 code. If you import a campaign with an event that already exists in the new release, the campaign is opened and updated to use the new version of the event. Identifiers that are associated with request variables or reply variables might be changed if there are existing identifiers that have the same name but are of a different data type. For more information see “Data Types” on page 11. The relationship between treatment campaign sets and decision treatment campaigns is maintained if all of the objects are imported into a path relative to the business context root path. If treatment campaign sets and decision treatment campaigns are imported at the same time, their relationship is maintained in any path that they are imported to. Import the campaign definitions and reply definitions into any folder within the business context folder. For more information about exporting and importing files, see “Best Practices for Exporting and Importing Objects” on page 223.

Common Data Model When you migrate files to the next release, the content of the common data model must also be migrated to the new environment. If the common data model content is not migrated, all campaigns must be republished in order to be able to execute campaigns and record history.

249

8 Managing the Environment Starting the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Backing Up and Restoring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 The Difference between Backing Up Data and Archiving Data . . . . . . . . . . . . . . 251 General Strategy for Backing Up Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Backing Up Files Before Installing a New Version . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Using SAS Integration Utilities to Back Up and Restore Campaigns . . . . . . . . . 253 Exporting SAS Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Checking for and Installing Hot Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Migrating to a New Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Configuring Additional SAS Federation Servers to Form a Server Cluster . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Install and Configure a New SAS Federation Server . . . . . . . . . . . . . . . . . . . . . . . Edit JDBC Connection System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Clustering Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

254 254 255 255 256

Processing Large Amounts of Data in Arbitration . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Arbitration Process Capacity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Reduce Data Sent to an Arbitration Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Requirements for the Remote Deployment Environment . . . . . . . . . . . . . . . . . . . 262 Requirements for Remote Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Requirements for the Design Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Accessing the External REST APIs for Integrated SAS Products . . . . . . . . . . . 263 Managing Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Managing Sessions in the istration Workspace . . . . . . . . . . . . . . . . . 264 Managing Sessions If Secure Sockets Layer (SSL) Is Configured . . . . . . 265 Update Dynamic Custom Detail Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Overview of Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Set Row and Item Recovery Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Set Separators for Lists and Treatment Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Set Logging Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Improving Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 Improving History Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 Improving Campaign Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

250 Chapter 8 / Managing the Environment Bulk-Load Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Specify Data Set Options without Bulk Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Examples: Data Set Options without Bulk Loading . . . . . . . . . . . . . . . . . . . . . . . . . 279 SAS Decision Services Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Data Produced per Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Data Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 SAS Environment Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Data Collection for Performance Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 Using the SAS Decision Services HQ Plug-in for SAS Environment Manager 283 JDBC Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Tuning Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Tuning Considerations for SAS Federation Servers . . . . . . . . . . . . . . . . . . . . . . . . 290 Tuning Considerations for Database Management Systems . . . . . . . . . . . . . . . . 290 Keeping Connections Alive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 HTTP Client Code Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAS Customer Experience Real-Time Server Integration . . . . . . . . . . . . . . . . . . . Web Service Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAS Decision Services Client API for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

291 291 292 292 292

Use of SAS Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Using SQLSTMT in Real-Time Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example 1: SQL Select Statement with Bound Variables . . . . . . . . . . . . . . . . . . . Example 2: SQL Select Statement without a Bound Variable . . . . . . . . . . . . . . . Example 3: SQL Insert Statement Using Bound Parameters . . . . . . . . . . . . . . . .

293 293 295 296 297

Suggested Initial Values for Key Tuning Elements in Systems with Heavy Workloads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 Best Practices for Optimum Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 Tuning JVM Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Tuning the JVM Memory Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Troubleshooting JVM Out-of-Memory Error Messages . . . . . . . . . . . . . . . . . . . . . 302 Audit Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Events Logged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Data Logged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 Release Locked Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Starting the Environment You must start the SAS Customer Intelligence components in the correct sequence in order for successful operation of the components. The metadata server must be started before you start the object spawner, SAS/CONNECT spawner, SAS/SHARE server, OLAP server, and DIP job runner. SAS Web

Backing Up and Restoring Data

251

Infrastructure Data Server (Postgres), SAS Web Server, JMS broker (Active MQ), and cache locator (GemFire) must be started before you start SASServer1 (Web Infrastructure Platform). SASServer1 (WIP) must be started before you start SASServer7. SASServer7 has a logical dependency on SAS Decision Manager data server (Postgres), and SAS Federation Server. The following diagram displays the start-up order for the SAS Customer Intelligence components.

SASServer2 (SAS Business Intelligence)

SAS OLAP Server

SAS/SHARE Server

SAS/CONNECT Spawner

Object Spawner

SAS Federation Server Manager

SAS Deployment Agent

SAS Information Retrieval Studio (Python)


SAS Decision Manager Data Server (Postgres)

Cache Locator (Gemfire)

SAS JMS Broker (Active MQ)

SAS Web Server (httpd)

SAS Metadata Servers

DIP Job Runner

SAS Web Infrastructure Data Server (Postgres)

Figure 8.1 SAS Customer Intelligence Architecture Start-Up Order

Not Started

SASServer1 (Web Infrastructure Platform)

Deployment Tester Remote Services

SASServer6 (SAS Customer Intelligence)

SASServer11 (SAS Model Manager)

SASServer12 (SAS Visual Analytics)

SASServer7 (SAS Decision Services)

SAS Environment Manager (Hyperic) SAS Environment Manager Agent

= SAS Customer Intelligence Critical Path = Startup Dependency = Logical Dependency

Backing Up and Restoring Data The Difference between Backing Up Data and Archiving Data The primary difference between the tasks of backing up data and archiving data is in their objectives. Backups are necessary for the operational recovery of IT business systems during a disaster (for example, a flood, lightning strike, or hard drive crash). Backups are typically stored for several weeks. A daily backup cycle can protect all types of business data, including structured and unstructured data. Archives (archived data) are created in order to comply with legislation and good corporate compliance practices. Archived data is typically kept for a number of years. To create an archive, manual processes are created to take a backup copy from its normal backup cycle and store it in a fireproof safe for long-term storage. The backup media represents a snapshot of the business at that point

252 Chapter 8 / Managing the Environment in time. An organization might use archived data to protect structured business data (for example, business transactions or legal contracts).

General Strategy for Backing Up Data Steps for Backing Up Data As part of the maintenance of SAS Customer Intelligence, you should perform the following steps: n Back up your SAS metadata repository either nightly or weekly. SAS

Customer Intelligence makes extensive use of metadata that is stored on the SAS Metadata Server and physical content that is stored on the SAS Content Server. Therefore, it is critical to perform regular backups of these servers. n Back up the SAS Content Server. n Keep separate XML backup files for each of the information maps and

campaign. Store the XML backup files on a separate file system in order to recover data that might be lost because of a hardware malfunction such as a hard drive crash. If one or more objects become corrupted, then you can re-import the XML backup file for a specific information map or campaign . In this way, you avoid restoring the entire SAS Metadata Server and SAS Content Server. Note: All of the data from the SAS Metadata Repository and the SAS Content Server must be backed up at the same time.

Synchronizing the Backups When you perform backups of the SAS Metadata Server and the SAS Content Server, the backups must be synchronized in order to correctly restore the SAS Customer Intelligence environment. In order for the backups to be synchronized, the metadata server must be paused during all of these backups. Pausing the server (and setting it to an Offline state) ensures that no Campaign activity can occur between the creation of the backups. Note: Pausing the server does not affect the flows that are running in the engine. Perform the backups in the following order: 1

Pause the SAS Metadata Server, and set it to an Offline state.

2

Back up either the SAS Content Server or the SAS Metadata Server.

3

Back up the remaining server (either the SAS Metadata Server or the SAS Content Server).

4

Resume the SAS Metadata Server.

For details about synchronizing your backups, as well as additional guidance for making backups, see SAS Intelligence Platform: System istration Guide. The guide is available at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html.

Backing Up and Restoring Data

253

Backing Up the SAS Metadata Server The SAS Metadata Server includes a server-based facility that performs metadata server backups automatically, on a scheduled basis, without the need for intervention. For more information, see SAS Intelligence Platform: System istration Guide, which is available at http://.sas.com/documentation/onlinedoc/ intellplatform/index.html.

Backing Up the SAS Content Server To back up the SAS Content Server, follow these steps: 1

Make sure that the SAS Metadata Server has been paused and set to an Offline state.

2 Stop either the web application server or the SAS Content Server application. 3

Use operating system commands or third-party tools to copy all of the files and subdirectories from the following path: SAS-configuration-directory\Lev1\AppData\SASContentServer \Repository

Backing Up Files Before Installing a New Version Before you install a new version of SAS Customer Intelligence, back up the following files in the SASHome\SASFoundation\9.4\ma\sasmacro directory: n mausrexp.sas n mausrupl.sas

Restore these files after installing the new version.

Using SAS Integration Utilities to Back Up and Restore Campaigns To create an XML backup file for a campaign, use the SAS Customer Intelligence Integration Utilities that are provided with SAS Customer Intelligence. For more information about the SAS Customer Intelligence Integration Utilities, see SAS Customer Intelligence Integration Utilities at http:// .sas.com/documentation/solutions/ci/index.html. Although the installation of the SAS Customer Intelligence Integration Utilities is optional, they are typically installed with SAS Customer Intelligence. If the utilities have not been installed at your site, then they can be installed from the media that you received when you licensed SAS Customer Intelligence. your on-site SAS personnel for details.

Exporting SAS Packages You can also back up files by exporting SAS packages. For more information, see “Importing and Exporting SAS Packages” on page 222.

254 Chapter 8 / Managing the Environment

Checking for and Installing Hot Fixes SAS provides hot fixes that solve issues with a software release. A hot fix might provide a quick solution to an immediate problem or perform required system maintenance. For information about hot fixes for SAS Real-Time Decision Manager, go to http://ftp.sas.com/techsup//hotfix/hotfix.html. You can check the version of the installed hot fix by viewing the configuration properties on the Diagnostics page.

Migrating to a New Release For information about migrating a previous release of SAS Real-Time Decision Manager to the latest release, see SAS Marketing Automation and SAS RealTime Decision Manager: Migration Guide.

Configuring Additional SAS Federation Servers to Form a Server Cluster Overview The standard SAS Decision Services installation and deployment process configures a single engine middle tier and a single SAS Federation Server. For production deployments, more than one middle-tier engine and co-located SAS Federation Server are typically configured to meet system performance and availability requirements. See “JDBC Performance Tuning” on page 286 for information about how to determine the number of servers to allocate to each tier. A minimum of two middle tier SAS Federation Servers are required to hardware failover. The SAS Decision Services engine load balances every SAS Federation Server for which there is a corresponding URL in the JDBC Connection system resource that is used for executing activities. Therefore, for proper operation, every such SAS Federation Server must have access to the same set of DS2 packages. This requires that every such SAS Federation Server be configured identically, with the same s, database s, and DSNs. If your DS2 packages are stored in SAS data sets, those data sets must be located in a shared directory that is accessible from all such SAS Federation Servers.

Configuring Additional SAS Federation Servers to Form a Server Cluster

255

Figure 8.2 Load Balancing

HTTP Server

S A S D ec is ion Se rv ices E ng in e





D ata b ase Activities (DS2)


Install and Configure a New SAS Federation Server See the SAS Decision Services 6.4 Configuration Guide for information about installing and configuring a SAS Federation Server. Be sure to configure the new SAS Federation Server identically to the one that is currently used to execute activities. It must have access to the same set of DS2 packages, and it must have the same s, database s, and DSNs defined.

Edit JDBC Connection System Resources Use the following procedure to edit your JDBC Connection System Resources to recognize the new SAS Federation Server that you configured earlier. If you are modifying a standard configuration, repeat this procedure for each of the system resources: n $SAS_Activity_Resource n $Score_JDBCConnectionResource n GeneralIO_Activity_Resource_FS (modify GeneralIO_Activity_Resource only

if you plan to use your new SAS Federation Server for SAS data set I/O). Open SAS Management Console, select the Folders tab, and follow these steps: 1

Expand System  Applications  SAS Decision Services  Decision Services 6.4.

2

Select the repository folder.

256 Chapter 8 / Managing the Environment 3

Right-click the desired system resource, and select Edit System Resource from the drop-down menu.

4

Modify the Server URL field only, by adding a space followed by the full URL, including protocol, of your new SAS Federation Server.

5 Click OK to save your changes.

Clustering Best Practices n If DS2 packages are stored in SAS data sets (the default configuration), they

must be located on a shared drive that is accessible by all SAS Federation Servers in the cluster. Otherwise, run-time errors will occur. Similarly, if the SAS Federation Server cluster is used to read data from SAS data sets, all servers must have access to the data sets on a shared drive. n Multiple SAS Federation Servers, which are listed in the Server URL field of

a system resource, are uniformly load balanced. Therefore, it is important to deploy each SAS Federation Server in a given cluster on the same class of hardware. If this practice is not complied with, the more powerful servers in the cluster will be under used and the less powerful servers might be overburdened. n If DS2 packages are stored in a third-party database (a custom

configuration), all SAS Federation Servers in the cluster must have access to the database and to the same DS2 packages.

Processing Large Amounts of Data in Arbitration Arbitration Process Capacity SAS Real-Time Decision Manager enables you to send a treatment table and treatment detail table to an arbitration process. However, when the total size of the encoded data for a transmitted table exceeds 32 kilobytes, the arbitration process returns the following error: java.sql.SQLException: Unable to execute query: T_BIND_PARAMS: Failure encountered: SAVE BINDINGS FAILED.

This problem is caused by a limit of 32 kilobytes on the size of strings that are ed from Java to the SAS DS2 language.

Reduce Data Sent to an Arbitration Process Overview of Arbitration Data By default, the arbitration process sends treatment table and treatment detail table columns that are referenced by the custom process code to DS2. The treatment table is created dynamically by the SAS Decision Services Design Server or Engine Server from the treatments that are valid and selected for a given customer at run time. That treatment table contains not only each

Processing Large Amounts of Data in Arbitration

257

treatment code and description, but also all of the custom attributes for every treatment.

Arbitration Data Tables Treatment tables are displayed in the test interface in SAS Customer Intelligence Studio. For more information, see SAS Real-Time Decision Manager: ’s Guide. The treatment tables and treatment detail tables contain the following columns. Note: _TREATMENTS, _TREATMENTS_CUSTOM_UDF, _TREATMENTS_CUSTOM_UDF_LISTS are the table names that are used inside the decision services flow. When the tables are sent to DS2, the following names are used instead: Treatments, Treatments_Custom, and Treatments_Custom_List. The treatments table is named _TREATMENTS. Table 8.1

_TREATMENTS Table

Column Name

Type

Description

TREATMENT_ID

Integer

treatment ID. This value is used to associate the treatment with custom details.

TREATMENT_DESC

String

treatment description

TREATMENT_REF_URL

String

treatment asset URL

TREATMENT_REF_TEXT

String

text label for the treatment asset URL

TREATMENT_CODE

String

treatment code

TREATMENT_NAME

String

treatment name

TREATMENT_COLUMN

String

column name that is displayed in SAS Real-Time Decision Manager. The format is usually TREATMENT_NAME_# where # is the copy number of the treatment in the package.

TREATMENT_SK

Integer

treatment surrogate key from the common data model

TREATMENT_TRACKING_CODE

String

tracking code to reference treatment in responses. The value corresponds to TREATMENT_HASH_VAL in the common data model.

TREATMENT_CONTRIB_CELL_P ACKAGE_SK

String

original marketing cell and audience that generated or identified the treatment

258 Chapter 8 / Managing the Environment TREATMENT_GUID

String

unique identifier used internally by SAS Real-Time Decision Manager

TREATMENT_FOLDER

String

local folder in metadata that contains the treatment

TREATMENT_PARENT_FOLDER

String

parent folders of TREATMENT_FOLDER , up to the business context folder

COUNT

Integer

number of occurrences of this treatment, if the treatment is either staged multiple times or is duplicated from other cells and audiences within decision treatment campaigns.

PROCESSED_DTTM

DateTime

date and time that treatment was processed

TREATMENT_START_DTTM

DateTime

treatment activation date

TREATMENT_END_DTTM

DateTime

treatment expiration date

TREATMENT_TARGET_START_ DTTM

DateTime

treatment presentation start date for staged treatments

TREATMENT_TARGET_END_DT TM

DateTime

presentation start date for staged treatments

TREATMENT_STAGED

Boolean

indicates whether this treatment was retrieved from staging. Value is false if the treatment is from the current campaign.

TREATMENT_SCORE

Double

numeric score. The score can be specified or is a random value when not specified.

TREATMENT_RANDOM_SCORE _FLG

Boolean

indicates whether TREATMENT_SCORE was populated from a random number

The treatment details tables are named _TREATMENTS_CUSTOM_UDF and _TREATMENTS_CUSTOM_UDF_LISTS. Table 8.2

_TREATMENTS_CUSTOM_UDF Table

Column Name

Type

Description

XREF_TREATMENT_ID

Integer

treatment ID. This value is used to associate the treatment with custom details.

NAME

String

custom detail name


259

TAG

String

custom detail tag associated with this custom detail

VAR_ID

String

unique variable ID associated with this custom detail, used internally by SAS Real-Time Decision Manager

TYPE

String

custom detail type. It can have the following values: S = String, B = Boolean, N = Numeric, D = DateTime, U = Link, A = List.

COLUMN_NAME

String

column in CI_TREATMENT_DYNAMIC_ATT RIBUTE_EXT to populate with this value

DYNAMIC_FLAG

Boolean

indicates whether this custom detail can be modified within a campaign or transaction

REQUIRED_FLAG

Boolean

indicates whether this custom detail must be assigned in the campaign

NUM_VALUE

Double

value associated with numeric custom details. For other custom details, the value is missing.

STRING_VALUE

String

value associated with string custom details and the display value associated with link custom details. For other custom details, the value is missing.

DATE_VALUE

DateTime

value associated with date custom details. For other custom details, the value is missing.

BOOLEAN_VALUE

Boolean

value associated with Boolean custom details. For other custom details, the value is missing.

LINK_VALUE

String

URL value associated with link custom details. For other custom details, the value is missing.

XREF_LIST_ID

String

ID used to associate multiple list custom detail values in _TREATMENTS_CUSTOM_UDF_ LISTS with this custom detail

Table 8.3

_TREATMENTS_CUSTOM_UDF_LISTS Table

Column Name

Type

Description

260 Chapter 8 / Managing the Environment LIST_ID

String

ID used to associate multiple list custom detail values with a custom detail in _TREATMENTS_CUSTOM_UDFS

VAR_ID

String

unique variable ID associated with the related custom detail, used internally by SAS Real-Time Decision Manager

ORDER

Integer

order for this value in the custom detail list variable

DISPLAY_VALUE

String

the display label for a list that is selected in SAS Real-Time Decision Manager. The value matches LIST_VALUE when list values are populated dynamically through variable assignments.

LIST_VALUE

String

the actual value of the list custom detail entry

TAG

String

the custom detail tag associated with the related custom detail

Reduce Number of Columns In the three treatment tables that are ed to arbitration processes, columns are automatically included if the column names are referenced in the DS2 package source code. The following treatment table columns are available: n TREATMENT_ID

Note: This column is always sent to an arbitration process. n TREATMENT_CODE n TREATMENT_COLUMN n TREATMENT_CONTRIB_CELL_PACKAGE_SK n TREATMENT_DESC n TREATMENT_FOLDER n TREATMENT_GUID n TREATMENT_NAME n TREATMENT_PARENT_FOLDER n TREATMENT_REF_TEXT n TREATMENT_REF_URL n TREATMENT_SK

The following UDF (-defined field) table columns are available: n XREF_TREATMENTS_ID

Note: This column is always sent to an arbitration process.


261

n NAME n BOOLEAN_VALUE n COLUMN_NAME n DATE_VALUE n DYNAMIC_FLAG n LINK_VALUE n NUM_VALUE n REQUIRED_FLAG n STRING_VALUE n TAG n TYPE n VAR_ID n XREF_LIST_ID

Note: This column is always sent to an arbitration process. The following UDF (-defined field) table columns that are assigned at run time are available: n LIST_ID

Note: This column is always sent to an arbitration process. n DISPLAY_VALUE n LIST_VALUE n ORDER n TAG n VAR_ID

The values in these columns are UDF list-type values where multiple rows might exist for multiple-select UDFs. Only one _VALUE column is populated per row, depending on type. Empty columns have negligible impact on an arbitration process.

Reduce Number of Rows You might want to improve performance by limiting the number of rows that are sent to an arbitration process. Your software might have technical limitations that require you to reduce the amount of data that is processed. If you have selected Arbitration as the process type for a SAS process in SAS Customer Intelligence Studio, use the Arbitration Settings page to control the number of custom details that are included in an arbitration.

262 Chapter 8 / Managing the Environment Figure 8.3 Specify Custom Details for Arbitration

By default, all custom details are included in an arbitration process. Alternatively, select Only custom details with dynamic values. Select Only custom details to add a tag to the list of specified tags. with specified tags and click

Requirements for the Remote Deployment Environment A deployment environment is a SAS Decision Services engine server where campaigns are deployed. Multiple instances of a deployment environment can be served by one design environment. For more information, see “Add Remote Deployment Environments” on page 232.

Requirements for Remote Publishing When you deploy to a remote environment, the associated campaigns must be published into the common data model that is associated with the remote environment. To do this, the following items are required: n DS2 history processes and flows that are activated in the engine repository. n In SAS Federation Server, the federated data source name (DSN) must be

populated with the common data model catalogs and schemas that match the source environment. n Libraries that are used by data processes in the decision flow must be

created with the same names in the run-time repository (pointing to the correct hostnames and using the appropriate names and s for the production environment).

Requirements for the Design Environment The design environment requires the following: n Libraries for the remote common data models. The libraries can have

different names. The libraries are created in the Data Library Manager. For more information, see “Add Remote Deployment Environments” on page 232. n Connectivity to the production common data model database from the design

environment STP servers.

Accessing the External REST APIs for Integrated SAS Products 263

Accessing the External REST APIs for Integrated SAS Products If you are using SAS Model Manager, SAS Business Rules Manager, or SAS Decision Builder with SAS Real-Time Decision Manager, and the products are not installed and licensed on the same environment as SAS Real-Time Decision Manager, you must perform the following steps to enable SAS Real-Time Decision Manager to access the external REST APIs (application programming interfaces) for the integrated products: Note: You must have access to the environments where the products are located. 1

Open the file that is used to start the SAS Web Application Server. On UNIX or Linux, the file is <SAS-configuration-directory>/ Lev1/Web/WebAppServer/SASServer6_N/conf/setenv.sh. On Windows, the file is <SAS-configuration-directory>\Lev1\Web \WebAppServer\SASServer6_N\conf\wrapper.conf

2

If you are using SAS Model Manager, add the following parameters to the file: -DMMGRWebServiceURL=http://myserver:portNumber -DMMGRWebServiceURL=my -DMMGRWebServiceURLPW=my

In the setenv.sh file, insert set JAVA_OPTS=%JAVA_OPTS% before each parameter. In the wrapper.conf, insert wrapper.java.additional.NN before each parameter. MMGRWebServiceURL specifies the SAS Model Manager server name (and port if necessary), MMGRWebServiceURL specifies the name for

authentication to the SAS Model Manager REST API, and MMGRWebServiceURLPW specifies the for the SAS Model

Manager REST API. Note: The name that you specify for DMMGRWebServiceURL must be a metadata that is a member of the SAS Model Manager s group on the system to which you are connecting. 3 If you are using SAS Business Rules Manager, add the following parameters

to the file: Note: SAS Business Rules Manager comes with SAS Real-Time Decision Manager. This step is required only if you are using an installation of SAS Business Rules Manager that is not in the same environment as SAS RealTime Decision Manager. -DBRMWebServiceURL=http://myserver:portNumber/SASBusinessRulesManagerWeb/rest/ -DBRMWebServiceURL=my -DBRMWebServiceURLPW=my

In the setenv.sh file, insert set JAVA_OPTS=%JAVA_OPTS% before each parameter. In the wrapper.conf, insert wrapper.java.additional.NN before each parameter.

264 Chapter 8 / Managing the Environment BRMWebServiceURL specifies the SAS Business Rules Manager server name (and port if necessary) followed by / SASBusinessRulesManagerWeb/rest/, BRMWebServiceURL specifies the name for authentication to the SAS Business Rules REST API, and BRMWebServiceURLPW specifies the for the SAS Business Rules Manager REST API.

Note: The name that you specify for BRMWebServiceURL must be a metadata that is a member of the SAS Model Manager s group on the system to which you are connecting. 4 If you are using SAS Decision Builder, add the following parameters to the

file: -DBDMWebServiceURL=http://myserver:portNumber -DBDMWebServiceURL=my -DBDMWebServiceURLPW=my

In the setenv.sh file, insert set JAVA_OPTS=%JAVA_OPTS% before each parameter. In the wrapper.conf, insert wrapper.java.additional.NN before each parameter. BDMWebServiceURL specifies the SAS Decision Builder server name (and port if necessary), BDMWebServiceURL specifies the name for authentication to the SAS Decision Builder REST API, and BDMWebServiceURLPW specifies the for the SAS Decision Builder REST API.

Note: The name that you specify for BDMWebServiceURL must be a metadata that is a member of the SAS Model Manager s group on the system to which you are connecting. 5

Restart each SASServer6_N instance.

Managing Sessions Managing Sessions in the istration Workspace As an , you might want to manage active sessions in SAS Customer Intelligence Studio. For example, you might need to log off from all sessions in order to provide system maintenance. To manage sessions, select the Sessions category in the istration workspace.

Update Dynamic Custom Detail Values

To log off from a session, select the session and click

265

.

Managing Sessions If Secure Sockets Layer (SSL) Is Configured If SAS Customer Intelligence is configured to use Secure Sockets Layer (SSL) at your site, you cannot log off s through the istration workspace unless you modify the SAS Web Application Server parameters. To modify the parameters, take the following steps: 1

Open the file that is used to start the SAS Web Application Server. On UNIX or Linux, the file is <SAS-configuration-directory>/ Lev1/Web/WebAppServer/SASServer6_1/conf/setenv.sh. On Windows, the file is <SAS-configuration-directory>\Lev1\Web \WebAppServer\SASServer6_1\conf\wrapper.conf

2 Add the following parameters to the file: -Dsas.ci.cluster.protocol=https -Dsas.ci.cluster.hostname=load-balancer-hostname -Dsas.auto.publish.port=443

If the environment is not configured to use the default port, use the HTTPS port number. 3

Restart the SAS Web Application Server.

Update Dynamic Custom Detail Values You can choose whether to update the values for dynamic custom details in a campaign when the values are changed in treatments. Add the option to the following file on every SASServer6 node where SAS Marketing Automation is deployed. On Windows, the file is LevConfig\Web\WebAppServer \SASServer6_cluster_number\conf\wrapper.conf. On UNIX, the file is LevConfig/Web/WebAppServer/ SASServer6_cluster_number/bin/setenv.sh. By default, dynamic custom details are updated only in a campaign when the custom detail names are not the same in the old and new version of the campaign. To specify that dynamic custom detail values are updated when the values change in a treatment, enter this option: -Dcom.sas.crm.overwrite_all_custom_details_on_treatment_update.enabled=true


Environment Variables Overview of Environment Variables The Environment Variables category in the Setup workspace enables you to modify environment settings such as log size. In SAS Real-Time Decision Manager, environment settings can be modified in other areas such as SAS Decision Services resource settings, JVM arguments, and thread settings. For more information about SAS Decision Services resource settings, see “Library Resources” on page 65. For more information about setting JVM arguments, see “Tuning the JVM Memory Size” on page 301. Figure 8.4 Environment Variables

Note: If more than one is editing environment variables at the same time, the last saved edits override previous edits.

Set Row and Item Recovery Options Row options are set on the General page. Figure 8.5 General Page

Enter a number in the Maximum rows displayed field to specify the maximum number of rows in a table that is displayed in SAS Customer Intelligence Studio. This setting affects external tables that contain the following items. n Events n Test cases n External treatments

Environment Variables

267

n Data grid variables n Batch input n Batch output

If you close or navigate away from an application window before you close an object such as a campaign, the object remains open on the server. If you return to the same session and attempt to reopen the object, the server verifies that the abandoned object is not already open in another window. Enter the number of seconds in the Reopen timeout field to specify the maximum amount of time that the server waits for a reply from an open window before restoring abandoned objects in a new window.

Set Separators for Lists and Treatment Values The separators for list and treatment values are displayed on the Campaign page. Figure 8.6 Campaign Page

To set the delimiter for list values that are returned into a string type reply variable, enter or select a separator in the Separator for list values list. To set the delimiter for the multiple treatment values that are provided in a package, enter or select a separator in the Separator for treatment values list. SAS Real-Time Decision Manager uses the delimiters that are specified in the SAS Decision Services global variables. If the global variables do not exist, SAS Customer Intelligence Studio creates them and the delimiter values that are created on the Campaign page are used as the initial values.

Set Logging Level In SAS Customer Intelligence Studio, the trace level for logging is set on the Logging page. Select a tracing level to set the amount of detail in log messages that are written to the \Lev1\Web\Logs\SASServer6_N directory. Off enables INFO, WARN, and ERROR level logging for normal operations. Medium enables INFO, WARN, ERROR, and DEBUG level logging. The DEBUG level creates more detailed information and is used to troubleshoot problems. The MEDIUM tracing level is not recommended for normal operations.

268 Chapter 8 / Managing the Environment High enables INFO, WARN, ERROR, DEBUG, and TRACE level logging. The TRACE level creates the most detailed information and is used to troubleshoot problems. The HIGH tracing level is not recommended for normal operations. This option controls the size of the log that is generated for any SAS code that is run during a SAS Customer Intelligence Studio session. Figure 8.7 Logging Page

For information about setting the levels for other logs in SAS Real-Time Decision Manager, see “Customizing Logs for Troubleshooting” on page 325.

Improving Performance Performance Considerations The performance of SAS Real-Time Decision Manager can be measured by volume and response time. Performance can be improved by load balancing, and by monitoring, tuning, and analyzing your environment. Performance can be hindered by the following activities: n processing large amounts of transactions or events per second n making external requests. Minimize external requests to improve

performance. For example, if the channel already has access to the data that you need for your campaign, it in through the event or the API request as much as possible instead of having each campaign execution require you to query the database again. Interacting with a separate application can take a lot of time. n using SAS custom code, such as DS2, for process nodes adds time and can

easily include inefficient code n using the SAS external web services activities

TIP When you use SAS external web service activities, use in-memory tables and caching to optimize performance, if possible.

Improving Performance

269

n managing large treatment sets n using heavy I/O interactions n managing data between Java data types and DS2. For more information, see

“Data Types” on page 160. When you choose a database to use with SAS Real-Time Decision Manager, consider the transaction and latency requirements of your site. Not all of the ed databases perform the same way in the same situation. For performance and tuning information about the type of workload that you expect, consult the product documentation for your database. Your hardware might not be efficient when processing a large number of treatment campaigns because it might not have enough memory to compute the offers in parallel.

Load Balancing Production workloads for SAS Real-Time Decision Manager must be split across two or more operational servers that contain a SAS Decision Services engine server and a SAS Federation Server. In order to balance incoming requests, a load balancer might be necessary. If a load balancer is already installed at a site, configure this component to direct traffic to the operational servers. Load balancing provides the following benefits: n volume management

if you have multiple copies of SAS applications, a load balancer determines which copy is sent a request in order to execute the instance. Having multiple copies of mid-tier applications such as the SAS Decision Services engine enables the processing of more requests than one application can handle. When a new event request comes in, the load balancer determines which copy of the application to send the request to. n high availability (to provide fault tolerance or redundancy)

load balancing enables high availability to provide many instances to use in case an application is offline n maintenance

load balancing enables you to keep the environment operational while you perform maintenance on a component. The following diagram displays the location of a load balancer in a configuration of SAS Real-Time Decision Manager.

270 Chapter 8 / Managing the Environment Figure 8.8 Load Balancing SAS Metadata Servers

Compute Servers Design Middle Tier 1

sas-rtdm-internal.acme.com “Client” Applications (SAS Customer Intelligence Studio, SAS Management Console, etc.)

SAS Web Server

Design Middle Tier 2

SAS Real-Time Decision Manager Tier 1

sas-rtdm-external.acme.com External Load Balancer

Channel Applications

SAS Real-Time Decision Manager Tier 2

Improving History Performance Activate a History Process Note: Campaigns are processed quicker when history transactions are not written to the common data model. Depending on the needs of your site, you might choose to activate a history process. You use a business context or a reply node to select a method for recording history transactions. History transactions to the common data model database can be recorded by one of the following methods: n DS2 Activities

In general, the DS2 activities method records history faster than other methods. This method uses DS2 code that comes with the product. The engine server makes a synchronous call to the SAS Federation Server and requests that it execute the DS2 code. The SAS Federation Server then executes the DS2 code to write the one row and returns an acknowledgment that it wrote the row. The SAS Federation Server inserts a single record for each executed flow that uses DS2. For more information, see “Flows” on page 60. Note: If you are using the DS2 activities method, the libref name for the common data model must match the SAS Federation Server catalog name. For more information, see “Creating Reporting Catalogs” on page 138.

Improving Performance Table 8.4

271

libref Names

n The CustIntelReporting middle-tier application uses a synchronous call to

queue up a record but the Write action occurs asynchronously. CustIntelReporting records history transactions when it receives messages from the engine server each time the engine server has history that it needs to record. The engine server sends a web request one row at a time to the middle-tier reporting application. CustIntelReporting collects the rows in an in-memory queue until it determines that it has enough rows to send them in batch to make a database call. The batch is then sent to a stored process that sends the transactions to the common data model. Note: If you use CustIntelReporting to publish history transactions to the common data model, you might need to tune the performance options for the stored process server and the object spawner. The sending of requests to write a history from the engine server to CustIntelReporting and the subsequent acknowledgment from the middle-tier application is a synchronous call. The reporting application immediately acknowledges the request and asynchronously writes the history transactions. If the reporting application is offline, the engine server will be delayed waiting for an acknowledgment from the application if the engine server needs to send history. To prevent the degradation of performance, CustIntelReporting must be available to acknowledge receipt of these rows if you configure it to write history. Note: A separate campaign must be created to record a presented treatment history or a response history for an existing campaign. It is a best practice to cluster multiple instances of SASServer6 that include the CustIntelReporting middle-tier application. A load balancer is required to distribute the load between the instances of SASServer6. System resources in SAS Decision Services need to point to the URL for the load balancer instead of to the URL for an instance of SASServer6. You will need to include the associated stored process for each instance of SASServer6 by setting the following JVM option: -Dsas.si.storedProcessPath

Note: In remote environments, web service flows for history, presented treatment history, and response history cannot be activated. Only the DS2 history flows can be activated for remote deployed flows. By default, the Web Service Definition Language (WSDL) values for SAS Decision Services system resources are populated with the correct address for application components. To prevent the overwriting of customized values for web services, enter an option in the following file on every SASServer7 node where SAS Real-Time Decision Manager is deployed.

272 Chapter 8 / Managing the Environment On Windows, the file is LevConfig\Web\WebAppServer \SASServer7_cluster_number\conf\wrapper.conf. On UNIX, the file is LevConfig/Web/WebAppServer/ SASServer7_cluster_number/bin/setenv.sh. To allow customized values, enter the following option. -Dcom.sas.analytics.crm.flow.inbound.assets.no_override_wsdl = true

The _SAS_CCS_VALUE_SEPARATOR delimiter for treatment custom details is used only when using the CustIntelReporting method for writing history. When this method is used, all the names, values, and column names of the string type treatment custom details are concatenated into a single string that is sent to the web service (for example, name1=value1=columnname1<separator>name2=value2=columnname2v alues). The delimiter determines where one value ends and another begins.

Therefore, if the values of the custom details contain the delimiter, the web service code incorrectly parses where the individual values end and begin, causing history updates to the common data model to fail. The values can also be incorrectly parsed if a delimiter is used for numeric or date values. Note: The _SAS_CCS_VALUE_SEPARATOR delimiter must be a character that is not in the name, column names, or values of any of the custom details. Otherwise, the history update does not work correctly. SAS Real-Time Decision Manager does not use CustIntelReporting when there is no history. To enable a history recording method, you must activate a history flow in SAS Management Console. If you do not want to use a recording method, activate a NULL flow. To switch methods, you use the Activate and Deactivate selections in SAS Management Console. You do not need to restart the application to switch methods. For more information, see “Activate and Deactivate Selected Campaigns in SAS Management Console” on page 244. You can create sub-flows for staging and history in two ways: by writing data to the common model in the SAS Customer Intelligence Reporting mid-tier application, or by writing data to the SAS Federation Server. This option provides you with greater flexibility in how you stage your treatments and populate your history. Web service history flows process history transactions asynchronously and in batch from the real-time campaigns. The web service history process is appropriate for systems that use massively parallel processing (MPP) or data warehousing. Through the use of DS2, direct-write history flows can initiate transactions for each treatment and history record that is processed by the system. Before activating a DS2 history process, make sure that the database is appropriately tuned and adequate for row-level transactions. The database must the latency requirements for your site. Note: When you run a campaign in Test mode, the DS2 flow is used by default to write data to the common data model. You can use one of the following options to specify a different flow for writing data: -Dcom.sas.crm.rtdm.chupdate_flow -Dcom.sas.crm.rtdm.dtupdate_flow -Dcom.sas.crm.rtdm.ptupdate_flow -Dcom.sas.crm.rtdm.rhupdate_flow


273

For example, to specify using a web service to update the history, enter the following option: -Dcom.sas.crm.rtdm.chupdate_flow=_SAS__HISTORY_WS_FLOW

Increase History Table Loading By default, there is one active stored process job to load each type of history table. You can increase the parallelism to execute more than one job for each table. To change the history loading settings, enter options in the following file on every SASServer6 node where SAS Real-Time Decision Manager is deployed. On Windows, the file is LevConfig\Web\WebAppServer \SASServer6_cluster_number\conf\wrapper.conf. On UNIX, the file is LevConfig/Web/WebAppServer/ SASServer6_cluster_number/bin/setenv.sh. To increase the number of concurrent jobs to load history, enter the following option. -Dcom.sas.analytics.crm.ccs.ch_stp_cnt =

To increase the number of concurrent jobs to load dynamic treatments, enter the following option. -Dcom.sas.analytics.crm.ccs.dt_stp_cnt =

To increase the number of concurrent jobs to load confirmed s, enter the following option. - Dcom.sas.analytics.crm.ccs.pt_stp_cnt =

To increase the number of concurrent jobs to load response history, enter the following option. -Dcom.sas.analytics.crm.ccs.rh_stp_cnt =

Setting Options for Record Collection and Stored Process Execution If you are using the reporting application to process history, you might need to change the settings for the CICommon web service. These settings control the number of records and the amount of time the web service retains the records before calling a stored process. To change the CICommon web service settings, enter options in the following file on every SASServer6 node where SAS Real-Time Decision Manager is deployed. On Windows, the file is LevConfig\Web\WebAppServer \SASServer6_cluster_number\conf\wrapper.conf. On UNIX, the file is LevConfig/Web/WebAppServer/ SASServer6_cluster_number/bin/setenv.sh. By default, the CICommon web service collects records up to a limit of 50000 before calling a stored process. If your site has the capacity, you can set a higher number of records. The minimum number of records is 1000. To change the maximum number of records, enter the following option.

274 Chapter 8 / Managing the Environment -Dcom.sas.analytics.crm.ccs.ccsservice.service.record_threshold =

By default, the CICommon web service collects records for up to ten seconds before calling a stored process. If your site has the capacity, you can set a longer time limit. To change the time limit, enter the following option. -Dcom.sas.analytics.crm.ccs.ccsservice.service.time_threshold =

To specify the number of minutes between each attempt to execute a stored process, enter the following option. -Dcom.sas.analytics.crm.ccs.ccsservice.service.retry_delay_duration =

To specify the number of times to retry a failed execution of a stored process, enter the following option. -Dcom.sas.analytics.crm.ccs.ccsservice.service.max_retries =
Improving Campaign Performance Update SAS Federation Server When you execute a decision campaign, the DS2 code runs in SAS Federation Server. If you use an older version of SAS Federation Server, then you might experience slow performance or unexpectedly high memory consumption, especially if you execute a large number of campaigns simultaneously. Upgrade SAS Federation Server to the latest release. For more information about SAS Federation Server, see SAS Federation Server: ’s Guide at http:// .sas.com/documentation/onlinedoc/fedserver/index.html

Setting SAS Server Options for SAS Federation Server Some options can be edited to improve the performance of SAS Federation Server. It is recommended that the logging be left on while setting up the server, and then turned off for production. When turned on, logging significantly reduces overall system performance. The logging levels that affect your DS2 activities are specified by the SAS logging facility configuration file that is installed with your SAS Federation Server. By default, the logging level is set to Info. For production, the application logger should be changed to Error.

After you disable logging, you must restart SAS Federation Server.

Use DS2 Packages Already in SAS Federation Server Memory SAS Real-Time Decision Manager enables you to insert DS2 code into your decision campaigns using SAS process nodes. The DS2 code in these nodes is triggered to run by the SAS Decision Services design server or engine server middle-tier application when the server executes your campaign. However, SAS


275

Federation Server actually compiles and runs the DS2 code. In order to communicate with SAS Federation Server, the design server and the engine server each maintains its own pool of connections to SAS Federation Server. Each connection loads a given DS2 package only when that package is requested for a campaign. After a DS2 package is loaded, it remains in that connection's memory until the connection is closed. DS2 packages that are already in memory execute significantly faster than DS2 packages that must be loaded. The advantages of using connections that already have DS2 packages loaded into memory are as follows: n A connection that has been called on to execute all of your various DS2

packages executes subsequent DS2 calls faster than a new connection does. n Older connections usually have more DS2 code loaded into their memory,

and therefore process campaigns more quickly than newer connections. n Reusing a given connection as much as possible produces better

performance than using the connections in sequence. n A heavily reused connection is more likely to include the DS2 package that

you need because it is already loaded into memory. n Because newer connections execute DS2 code more slowly, performance

measurements should not be taken in an environment that has recently been restarted. n Restarting the connections between SAS Decision Services servers and SAS

Federation Server adversely affects performance. The following events reset connections: n restarting SAS Federation Server n restarting the SAS Decision Services server (the design server or the engine

server) n invalidating a particular connection because a time-out value is exceeded

during execution of DS2 code Note: The invalidation of a particular connection can be triggered by poor back-end database performance if your DS2 code makes SQL calls to the database. When one connection is invalidated, it triggers a cascade in which all connections are reset. This restart can cause slower performance, which can trigger more time-out conditions.

Use a Network-shared Drive to Store DS2 Packages SAS Real-Time Decision Manager availability and execution speed often benefit from the use of more than one SAS Federation Server in one environment. This configuration is especially helpful in environments that heavily use scoring or custom activities in their decision campaigns. In order to ensure that newly published models and activities are available to every SAS Federation Server in your environment, use a shared drive for storing DS2 packages. This shared drive must be accessible from each SAS Federation Server instance.


Bulk-Load Settings Bulk-load settings are used only by the CustIntelReporting history processes and by SAS Marketing Automation. If you are using SAS Marketing Automation or stand-alone SAS Real-Time Decision Manager, and transactions to flows exceed 500 transactions per second (TPS) where history is enabled, you can increase performance by setting the bulk-load settings for the business context.

Enable the Bulk-Load Facility Specify the following options in the Options section of the Settings tab in the Business Context Properties window. Example entries for each database are provided in “Example: Enabling the Bulk-Load Facility” on page 276. 1 Data set options specifies options that are used in the SAS DATA step to

create the temporary table. To enable the bulk-load capabilities of the database, specify BULKLOAD=YES. Additional options might also be appropriate, depending on which database you are using. For recommended options, see “Example: Enabling the Bulk-Load Facility” on page 276. If a bulk-load facility is not available for your database, or if you choose not to use the bulk-load facility, see “Specify Data Set Options without Bulk Loading” on page 278. 2

Schema specifies the location for the temporary tables. The following options are valid. n Specify your CICOMMON schema if you want the temporary tables to be

created in the same schema that stores history. n Specify another schema to use for the temporary tables. n Leave the field blank if you want the temporary tables to be created in the

’s default schema. n s must have both Read and Write access to the specified schema,

including the following: o

the ability to create and drop tables and indexes

o

the ability to delete, insert, and update records

n If you are using a Netezza database, specify the name of the database

where you want the temporary tables to be created. 3 Use temporary table capability of database specifies whether the

database’s native temporary table capability is to be used to create temporary tables. The check box is deselected by default. If you are enabling the bulk-load facility of your database, do not select this check box. CAUTION! If you specify both BULKLOAD=YES and Use temporary table capability of database, processing fails.

Example: Enabling the Bulk-Load Facility The following examples provide recommended values for enabling the BULKLOAD option for your database. Enter the data set options, schema, and Use temporary table capability of database options on the Options tab of the Business Context Properties window, as described see “Enable the Bulk-Load


277

Facility” on page 276. For information about enabling the bulk-load facility of other databases, visit http://.sas.com/documentation/index.html and search for the keywords “bulk-load facility.” To improve performance for all databases, add the following options to the marketingautomation_autoexec_mods.sas file. options dbidirectexec; %let SYS_SQL_IP_SPEEDO=YES;

Here are example bulk-load facility values for DB2: Note that the bulk-load facility for DB2 is called CLI LOAD. n Data set options: BULKLOAD=YES BL_METHOD=CLILOAD n Schema: <schema-name> n Use temporary table capability of database: Not selected

Here are example bulk-load facility values for Netezza: n Data set options: BULKLOAD=YES BL_OPTIONS="’LOGDIR’C:

\NETEZZA_LOGS\’" n Schema: database-name n Use temporary table capability of database: Not selected

Here are example bulk-load facility values for Oracle: Note that the bulk-load facility for Oracle is called SQL*Loader. Temporary tables are stored in the specified schema. n Data set options: BL_DIRECT_PATH=YES BULKLOAD=YES

BL_DEFAULT_DIR="C:\ORACLE_LOGS\" n Schema: schema-name n Use temporary table capability of database: Not selected

Here are example bulk-load facility values for SQL Server - OLE DB Connection: n Data set options: BULKLOAD=YES n Schema: (optional) n Use temporary table capability of database: Not selected

Here are example bulk-load facility values for SQL Server - ODBC Connection: n Data set options: BULKLOAD=YES n Schema: (optional) n Use temporary table capability of database: Not selected

Here are example bulk-load facility values for Teradata: Note that the bulk-load facility for Teradata is called FastLoad. Temporary tables are stored in the specified schema. n Data set options: BULKLOAD=YES SLEEP=1 TENACITY=1 n Schema: (None) n Use temporary table capability of database: Not selected

If you are storing MATABLES in a separate database, add the schema name. Do not select Use temporary table capability of database.

278 Chapter 8 / Managing the Environment You can also use the Teradata Parallel Transporter (TPT) to implement FastLoad. To start FastLoad in the SAS/ACCESS interface using the TPT API, specify the TPT=YES data set option in a processing step that populates an empty Teradata table. For more information, see SAS/ACCESS for Relational Databases: Reference at http://.sas.com/documentation/onlinedoc/access/ index.html.

Specify Data Set Options without Bulk Loading If a bulk-load facility is not available for your database, or if you choose not to use the bulk-load facility, specify the following options in the Options section of the Settings tab in the Business Context Properties window. Example entries are provided in “Examples: Data Set Options without Bulk Loading” on page 279. 1 Data set options specifies options that are used in the SAS DATA step to

create the temporary table. To improve performance, specify the INSERTBUFF option. 2

Schema specifies the location for the temporary tables. The following options are valid. n If you want the temporary tables to be created in the ’s default

schema, leave the field blank. n If you are selecting the Use temporary table capability of database

option, which uses the native temporary table capability of the database to create temporary tables, leave the Schema field blank. The Schema field is ignored if Use temporary table capability of database is selected. n Specify your CICOMMON schema if you want the temporary tables to be

created in the same schema that stores history. n Specify another schema to use for the temporary tables.

s must have both Read and Write access to the specified schema, including the following: n the ability to create and drop tables and indexes n the ability to delete, insert, and update records 3 Use temporary table capability of database specifies whether the

database’s native temporary table capability is to be used to create temporary tables. The check box is deselected by default. You should select this check box only if your site does not authorize s to create any additional temporary tables. When you select the check box, the following. n The value in Schema is ignored, and the location of temporary tables is

determined by the database. n Do not specify BULKLOAD=YES in the Data set options field. If you

specify both BULKLOAD=YES and Use temporary table capability of database, processing fails.

SAS Decision Services Monitoring

279

Examples: Data Set Options without Bulk Loading Overview The following examples show data set options that are recommended when a bulk-load facility is not available. Enter these values on the Settings tab of the Business Context Properties window, as described in “Specify Data Set Options without Bulk Loading” on page 278.

Example for a Relational Database for Which a Bulk-Load Facility Is Not Available Because no schema is specified in this example, the ’s default schema is used. n Data set options: INSERTBUFF=1000 n Schema: (None) n Use temporary table capability of database: Not selected

Example for a Relational Database When s Are Not Authorized to Create Additional Tables n Data set options: INSERTBUFF=1000 n Schema: (None) n Use temporary table capability of database: Selected

SAS Decision Services Monitoring Overview The SAS Decision Services Monitor provides an API for querying activity hit counters and execution performance statistics. The Monitor also controls production batch execution, and provides access to batch job progress, status, and results. The SAS Decision Services Monitor collects performance statistics from SAS Decision Services engines, saves them in a database, and s querying this data. The following describes the implementation of the SAS Decision Services Monitor.

Data Produced per Engine SAS Decision Services engines expose the following statistics for monitoring: n Event counts — The number of times an event is executed. n Node counts — The number of times a particular node of a flow is executed. n Flow response time —The average response time of a flow in milliseconds.

280 Chapter 8 / Managing the Environment The monitoring framework monitors the SAS Decision Services engine, or a cluster of engines, collects the information over a specified duration, and queries on the data. Because monitoring data is aggregated across the servers of a cluster, there are finite limits on the granularity of data collection and the amount of data stored. These affect the accuracy of the queries. In general, the higher the accuracy, the more the storage and U cycles are required to collect the data. Because there are multiple independent components in a SAS Decision Services engine cluster that might concurrently write to a database, only databases that concurrent writes can be used to collect monitoring data. Although it is recommended that SAS Decision Services engines are installed on a cluster for high availability, the monitor also s non-clustered deployments of SAS Decision Services engines.

Data Collection Overview The monitor polls all SAS Decision Services engines in the cluster to retrieve statistics on a regular basis. The data collection interval is configurable with reasonable restrictions. For information about parameters that control the frequency of data collection, see “Configuration” on page 281. The engines continue to process data, whether the monitor retrieves data from it or not. Upon start-up, the monitor scans the Topology table for the list of engines running in a cluster. This table is scanned only at start-up. Any changes to the topology are not picked up by the monitor until the monitor web application is restarted.

Independent Threads Although it is not possible to guarantee a strict data collection interval, the system makes a best effort to do so. During data collection, the monitor communicates to the engines using spring remoting (Java serialization over HTTP). If an engine is down, the HTTP call will time out. Depending on network configuration, this might take time. To make the calls to the engines independent of each other, the monitor collects data from engines on separate threads.

Duration The statistics that are retrieved represent an interval of time. The duration is determined by the time between the last retrieval from the engine (or the start of the engine) and the current time of retrieval. Any changes to event and node counts are captured. The average response time for flows is also captured. This means that if the monitor is stopped and restarted, the duration will be longer than usual and will include the counts during the time the monitor was not available. If an engine server crashes, accumulated counts since the last collection are lost. Therefore, using large data collection intervals can compromise the accuracy of the counts. On the other hand, more frequent collection uses more resources.

Starting and Stopping Data Collection Although the monitor constantly polls the engines for data, the engines do not collect data until a call to start data collection is received. When a call to start

SAS Decision Services Monitoring

281

data collection is received by the monitor, it communicates this to one of the engines. A flag indicating whether data collection is enabled is held in the distributed cache accessible by all engines. The engine receiving the command updates this flag. All live engines periodically check this flag to determine whether it should start collecting data (or continue to do so) or stop collecting data. Engines that are not live can pick up the change in status when they come back up. If data collection is enabled, the engines also scan the distributed cache for active flows and events, and then synchronize the counters for events and flow nodes to reflect the cache contents. A similar call is available to stop data collection. Not all applications might find the real-time counts useful. In such cases, the calling application should turn off data collection to reduce the load on the system. The system can also be configured to start up and turn on data collection without explicitly requiring the command to turn it on. In earlier releases of SAS Decision Services, a system property could be set to true to configure the system to do so. This system property is now also available as a configuration parameter for the system.

Persistence Overview Data collected from engines are persisted in a relational database. In the event of the monitor process going down, historical data is retained.

Data Collected As mentioned earlier, three types of data is collected: event counts, node counts, and flow response times. Changes to event and node counts for a duration are persisted in a record that includes the name of the event or the qualified name of the node (including the name of the flow), the count, engine information (address and port), and the start and end time of the duration. If the count for an event or node does not change in a duration, the record is not written. Similarly, the average response time for a flow is also persisted in a record that includes the name of the flow, the average time in milliseconds, details of the engine, and the duration. For activity method call nodes, metadata such as the name of the activity and the method called is also persisted. However, this information is not duration oriented and only the time at which this is retrieved is persisted.

Configuration The system s the following configuration items that control monitoring: Item

Configuration Property

Definition

Query interval

sasds.monitor.query.statisti cs.interval.seconds

The interval in seconds when polling the engines for statistics. The default value for this parameter is 5 seconds.

282 Chapter 8 / Managing the Environment Item

Configuration Property

Definition

Engine time out

sasds.monitor.engine.quer y.timeout.seconds

The maximum time to wait before the call to the engine to collect statistics is timed out. The default value for this parameter is 1 second.

Engine query thread pool parameters

sasds.monitor.query.thread .pool.*

The parameters for setting up the thread pool, for the threads that collect statistics from the engines in the cluster.

Note: The * indicates the inclusion of all of the properties that start with dcsv.monitor.execution.thre ad.pool. Data pruning enabled

sasds.monitor.clearOldRec ords

If true, this will periodically clear old records. The default value is True.

Number of days of data to maintain

sasds.monitor.keepRecord sForDays

If sasds.monitor.clearOldRec ords is True, then this deletes records older than the specified days from the current date. The default value is 30.

Continuous monitoring

sasds.engine.data.collectio n.enableOnStartup

If this condition is true, the monitoring will always be on.

Cache check frequency

sasds.engine.data.collectio n.cache.check.millisecond s

How frequently the system checks for changes in active flows in the cache, in milliseconds. The default value for this parameter is 1000.

Enable statistics collection when restarted

sasds.engine.data.collectio n.enableOnStartup

If this condition is true, then the system enables data collection whenever it is restarted without requiring an explicit start command. The default value for this parameter is False.

SAS Environment Manager SAS Environment Manager can be used to monitor hit counters, flow performance, and system heath information. For more information, see “Data Collection for Performance Analysis” on page 283.

Data Collection for Performance Analysis

283

Data Collection for Performance Analysis Using the SAS Decision Services HQ Plug-in for SAS Environment Manager Overview Using the SAS Decision Services HQ Plug-in for SAS Environment Manager, you can collect engine performance data, such as event hit counts, node hit counts, and average flow response time. The plug-in also provides system health information. Every tracking service is displayed as an individual service under SAS Decision Services Monitoring Server. You can also find physical memory size, virtual memory size, and U usage percentage information. In order for SAS Environment Manager to access the SAS Decision Services monitoring plug-in, a SAS Environment Manager agent needs to be installed on each server in a SAS Decision Services engine cluster. The auto-discovery process might take longer than 30 minutes, depending on the background process of the SAS Environment Manager server. After the SAS Decision Services monitoring plug-in is in the inventory of the SAS Environment Manager server, you can select the SAS Decision Services resource that is linked to the SAS Decision Services monitoring server, in order to collect the engine performance data. For more information about SAS Environment Manager, see SAS Environment Manager ’s Guide at http://.sas.com/documentation/onlinedoc/sev/ index.html.

Monitoring Service Inventory To view the overall monitoring services, click Inventory on the SAS Decision Services Monitoring Server screen. The current monitoring services are listed under Services. The total number of services, as well as a list of services by type, is displayed at the top of the Service section. This gives you a good sense of what events, nodes, and flows are being monitored. You can click the name of any of the services in the list to find general information about that service.


Event Hit Counts When an event is monitored, the SAS Decision Services monitoring plug-in periodically receives hit counts from the monitoring server. The hit counts for each event are accumulated from the time the SAS Decision Services server is started. The default tracking interval is set to one minute. The tracking interval can be changed. For more information, see “Configuring the Monitoring Interval” on page 285. Under Monitor, click Decision Services Monitoring Server 6.4 Decision Services Event to see the total hit counts indicator chart for all events. To see the hit counts for an individual event, click the event listed under Group . To see a detailed tracking chart, click Event Hit Counts located above the indicator chart. Click Metric Data to view the current monitoring numeric data table.

Data Collection for Performance Analysis

285

Node Hit Counts Node hit counts work in the same way as event hit counts. When a node is monitored, the SAS Decision Services monitoring plug-in periodically receives hit counts from the monitoring server. Also, like an event hit count, the hit counts for each node are accumulated from the time the SAS Decision Services server is started. The default tracking interval is set to one minute. The tracking interval can be changed. For more information, see “Configuring the Monitoring Interval” on page 285. Under Monitor, click Decision Services Monitoring Server 6.4 Decision Services Node to see the total hit counts indicator chart for all nodes. To see the hit counts for an individual node, click the node that is listed under Group . To see a detailed tracking chart, click Node Hit Counts located above the indicator chart. Click Metric Data to view the current monitoring numeric data table.

Average Flow Response Time When a flow is monitored, the SAS Decision Services monitoring plug-in periodically receives the average response time in mini-seconds from the monitoring server. The average response time for each flow is accumulated from the time the SAS Decision Services server is started. The default tracking interval is set to one minute. The tracking interval can be changed. For more information, see “Configuring the Monitoring Interval” on page 285. Under Monitor, click Decision Services Monitoring Server 6.4 Decision Services Flow to see the average response time indicator chart for all flows. To see the average response time for an individual flow, click the flow listed under Group . To see a detailed tracking chart, click Average Response Time located above the indicator chart. Click Metric Data to view the current monitoring numeric data table.

Configuring the Monitoring Interval The default tracking interval is set to one minute for all monitoring services. To change the interval, follow these steps: 1

Switch to Metric Data view by clicking Metric Data from any monitoring service.

2

Select the metric data in the first column of the table by clicking the check box.

3

Change the time interval in the text field by entering any integer.

286 Chapter 8 / Managing the Environment 4

Click Go to finalize the change.

Using the Control Actions Click Control on the SAS Decision Services Monitoring Server screen to send control commands to the monitoring server. From the Control Action drop-down menu, select one of the following commands: Check Data Collection Status displays the current data collection status. Remove All Realtime Data cleans up all real-time data in the data collection table. Enable Realtime Data Collection enables statistics collection on the monitoring server. Disable Realtime Data Collection disables statistics collection on monitoring server. All commands are sent through the web service call.

JDBC Performance Tuning Tuning Controls Two JDBC Connection resources are configured for three separate purposes: n To allow decision service activities to execute DS2 package methods, which

are hosted by SAS Federation Server. These package methods are used for scoring, or for executing custom SAS code. n To enable General I/O activities to read from and write to relational

databases such as Oracle, DB2, Teradata, and Microsoft SQL Server. n To enable General I/O activities, which are configured to access SAS data

sets, to read SAS data sets through SAS Federation Driver for Base SAS. SAS Decision Services uses Apache Commons Database Connection Pooling (DB) to affect efficient caching and management of JDBC Connections, parameterized prepared statements, and parameterized callable statements. For more information about Apache Commons DB, see http:// commons.apache.org/db/index.html. DB pool tuning values are stored in JDBC Connection resources. To access the pool tuning controls, select the Folders tab of SAS Management Console, and follow these steps: 1

On the Folders tab, expand System  Applications  SAS Decision Services  Decision Services 6.4.

2 Right-click the JDBC Connection resource that you want to configure, and

select Edit System Resource. Additional JDBC Connection resources can be added to enable access to additional database management systems. Note: The number of free database connections that are needed by the SAS Decision Services engine can be estimated by adding up the maximum number

JDBC Performance Tuning

287

of connections for each JDBC Connection resource that connects to the database in the Decision Services Manager plug-in. Figure 8.9 Create a JDBC System Resource - Advanced

Each attribute can be disabled or enabled by selecting the check box in the Configured column. You can also enable or disable all attributes by selecting Enable All. If all of the attributes are disabled in either Connection Pooling or Statement Pooling, the XML element is not created in the JDBC resource. If the pooling control is saved with the JDBC resource, you will see the advanced dialog box when you edit this system resource the next time. You can click Reset to Default to return to the basic dialog box. Any connection or statement pool setting that is not explicitly configured in the JDBC resource, uses a default

288 Chapter 8 / Managing the Environment value that is defined by Apache Commons DB. These default values are listed below in the descriptions of each pool tuning control. Note: It is recommended to use the default values in the Statement Pooling . After you click OK, the new JDBC Connection system resource appears in the repository. The and definitions that follow are also listed in the Help for this dialog box. Lifo determines whether the pool returns idle objects in last-in-first-out order. The default setting for this parameter is true. It is recommended that you use the default setting. However, you can change the setting to prevent firewalls or databases from automatically closing connections that have stayed idle too long. If you have a number of idle connections in your connection pool, the default setting is to reuse the most-used connections because these connections have stored information and therefore will execute the fastest. If there are a number of idle connections, those connections will be automatically closed. SAS Decision Services handles connections that have been closed from the outside. SAS Decision Services automatically drops every connection in its pool and re-creates the connection pool. Consequently, you will receive time-outs on the campaigns that you are trying to execute during the period of time when the connections are dropped and the connection pool is being re-created. It is recommended that you make the pool small to minimize the number of idle connections or make the pool larger and change the Lifo parameter so that you do not always use the top of the stack. Or do not use a firewall or database that closes connections from outside that have been lying idle between the middle-tier engine server and your database. MaxActive controls the maximum number of objects that can be allocated by the pool (checked out to clients or idle awaiting check-out) at a given time. When the value is non-positive, there is no limit to the number of objects that can be managed by the pool at one time. When MaxActive is reached, the pool is said to be exhausted. The default setting for this parameter is 12. TIP In the Connection Pooling , it is recommended to set this value

to be twice the number of cores that are available to the Design Server or Engine Server, depending on which repository the object you are editing belongs to. MaxIdle controls the maximum number of objects that can sit idle in the pool at any time. When the value is negative, there is no limit to the number of objects that can be idle at one time. The default setting for this parameter is 16. TIP In the Connection Pooling , it is recommended to set this value

to be twice the number of cores that are available to the Design Server or Engine Server, depending on which repository the object you are editing belongs to.

JDBC Performance Tuning

289

MaxWait the maximum amount of time, in milliseconds, to wait for an idle object when the pool is exhausted. The default setting for this parameter is -1, which means the wait can continue indefinitely. MaxTotal sets a global limit on the number of objects that can be in circulation (active or idle) within the combined set of pools. When the value is non-positive, there is no limit to the total number of objects in circulation. When maxTotal is exceeded, all keyed pools are exhausted. When maxTotal is set to a positive value, and borrowObject is invoked when at the limit with no idle instances available, an attempt is made to create room by clearing the oldest 15% of the elements from the keyed pools. The default setting for this parameter is 16 (no limit). MinEvictableIdleTimeMillis specifies the minimum amount of time that an object can sit idle in the pool before it is eligible for eviction because of idle time. When the value is nonpositive, no object is dropped from the pool because of idle time alone. This setting has no effect unless TimeBetweenEvictionRunsMillis is greater than 0. The default setting for this parameter is 120000 milliseconds. MinIdle sets a target value for the minimum number of idle objects (per key) that should always be available. If this parameter is set to a positive number and timeBetweenEvictionRunsMillis is greater than 0, each time the idle object eviction thread runs, it tries to create enough idle instances so that the specified number of idle instances will be available under each key. This parameter is also used by preparePool, if true is provided as that method's populateImmediately parameter. The default setting for this parameter is 4. NumTestsPerEvictionRun determines the number of objects to be examined in each run of the idle object evictor. This setting has no effect unless TimeBetweenEvictionRunsMillis is greater than 0. The default setting for this parameter is 10. TestOnBorrow whether to validate objects before they are returned by the borrowObject() method. TestOnReturn whether to validate objects after they are returned to the returnObject(java.lang.Object) method. TestWhileIdle whether to validate objects in the idle object eviction thread, if any. TimeBetweenEvictionRunsMillis the amount of time to sleep between examining idle objects for eviction. The default value is 120000 milliseconds. WhenExhaustedAction specifies the behavior of the borrowObject() method when the pool is exhausted. SoftMinEvictableIdleTimeMillis the minimum number of milliseconds an object can sit idle in the pool before it is eligible for eviction. There is an extra condition that at least MinIdle number of objects remain in the pool.


Tuning Considerations for SAS Federation Servers A SAS Federation Server maintains a thread of execution per open JDBC Connection. Therefore, the size of the connection pool has a direct effect on the number of threads that are available to service requests for activity method execution. For best performance, you want SAS Federation Server to maintain an optimum number of ready-to-run threads. For this reason, maxIdle and maxActive should be set to the same value, so that idle connections are not closed, and you want this value to equal the optimum number of threads. Because of the wide variation in server capabilities, you might need to experiment to find this optimum number. A good starting point is to set maxIdle and maxActive equal to twice the number of cores in SAS Federation Server. Adjust this number up and down while measuring U use, latency, and throughput in order to achieve an optimal setting. Specifying too few threads under uses the hardware, and too many threads causes SAS Federation Server to thrash. Therefore, these settings are critical to the performance of your system. The size of the statement pool should be large enough to contain an entry for every activity method deployed to the system. A statement pool is allocated per connection, so do not multiply the number of statements by the number of connections. Instead, simply use the number of statements as the maxActive value. If memory is at a , the maxIdle value can be adjusted down to reclaim space taken up by methods that are only rarely called.

Tuning Considerations for Database Management Systems Database performance tuning is a highly complex and specialized topic beyond the scope of this document. It depends on many factors, including network bandwidth, cache size, data transfer rates, disk array configuration, application characteristics, and more. See your database management system vendor for assistance.

Keeping Connections Alive A database connection is essentially a socket connection. Operating systems, database hosts, and firewalls drop idle T connections after a period of time. The following settings, which are not default, run an evictor thread every 30 minutes to evict any idle connections older than 30 minutes. This prevents connection failures because of invalid T connections, in most cases. The connection pools are reset when the system is synchronized. Synchronization occurs whenever a flow is activated or deactivated, or when Synchronize with Repository is selected from the Decision Services Manager plug-in for SAS Management Console. Setting

Example

TimeBetweenEvictionRunsMillis

1000 * 60 * 30

NumTestsPerEvictionRun

3

MinEvictableIdleTimeMillis

1000 * 60 * 30

HTTP Client Code Usage

291

There is a one-to-one relationship between the number of request processing threads that are allocated within SAS Federation Server and the size of the SAS Federation Server JDBC connection pool. Therefore, pool size affects performance. See your database vendor for information about performance tuning JDBC connection and statement pools.

HTTP Client Code Usage Overview SAS Decision Services uses Apache HTTP Client code in the following areas: n SAS Customer Experience Real-Time Server integration n Web service integration (including the SAS Customer Intelligence

and Response History) n SAS Decision Services client API for Java

The Apache HTTP Client exposes a number of configuration parameters through its preferences API: http://hc.apache.org/httpclient-3.x/preferenceapi.html. Choose parameter values carefully to ensure good performance. Here are common values: http.protocol.version Set this value to HTTP/1.1, as it is more efficient. http.protocol.expect-continue Set this value to false for SAS Customer Experience Real-Time Server integration, SAS Decision Services client API for Java, and for SAS Customer Intelligence Common Services. It eliminates the step where the client determines whether the server is willing to accept the request. In most cases, the server is willing. http.protocl.cookie-policy Set this value to ignore cookies. The use cases do not require them. http.socket.timeout In most cases, set this value to 1000 ms. Often, SAS Decision Services must a subsecond response. A different value can be set depending on your performance requirements. A large time-out value can result in a less responsive system. http.t.nodelay A value of true is recommended because it reduces network latency. http.connection.timeout In most cases, set this value to 1000 ms. This is the time to create a new connection. Because connections are pooled at steady state, new connections are not created as often. http.connection.stalecheck A value of false is recommended so that the success case is faster. Setting this value to true causes the client to check every connection before it is used, which adds time to every call.

292 Chapter 8 / Managing the Environment http-connection-manager.max-per-host Set this value based on server capability. For example, if the server can 1000 concurrent HTTP connections, set this value at 1000. Every instance of the HTTP Connection system resource, web service activity resource, and the SAS Decision Service RequestFactory creates a pool of connections, all for the same URL (for example, the same host). http-connection-manager.max-total Set this value to be the same as max-per-host because every pool s only a single host. http-connection-manager.class Set this value to org.apache.commons.httpclient.MultiThreadedHttpConnectionManager.

SAS Customer Experience Real-Time Server Integration For SAS Customer Experience Real-Time Server integration, the parameters can be set by editing the HTTP Connection system resource in the SAS Decision Services plug-in for SAS Management Console. For more information, see “Specify a New System Resource as an HTTP Connection” on page 126.

Web Service Integration Not all of the Apache HTTP Client properties are ed. The following properties are ed and are set using Java system properties, which can affect all web service activities and resource combinations. System Properties

HTTP Client Properties

Default Values (if not set)

com.sas.sasds.maxHostC onnections

http-connectionmanager.max-per-host

1000

com.sas.sasds.maxTotalC onnections

http-connectionmanager.max-total

10000

com.sas.sasds.staleChecki ngEnabled

http.connection.stalecheck

true

com.sas.sasds.tNoDelay

http.t.nodelay

true

com.sas.sasds.connection Timeout

http.connection.timeout

1000

SAS Decision Services Client API for Java The properties that are mentioned above can be set by ing a Java properties object that contains the name and value of the parameters when instantiating the SASDSRequestFactory object. Here is an example: String uri = "http://abcd.com/test"; Properties props = new Properties();

Using SQLSTMT in Real-Time Applications

293

props.set("http.protocol.version", "HTTP/1.1"); props.set("http.connection.timeout", "1000"); props.set("http.t.nodelay", "true"); SASDSRequestFactory factory = SASDSRequestFactory.getInstance(uri, props);

Note: These values are always set as String values.

Use of SAS Data Sets SAS data sets can be used by SAS Decision Services to hold data, as well as DS2 activity code and score code. To access data that is held in SAS data sets, you must configure a DSN in SAS Federation Server that uses the Base driver, and then use this DSN (or a federated DSN that includes this DSN) in the resource definition. The folder that contains the data sets must be accessible to SAS Federation Server. If multiple SAS Federation Servers are in use to implement failover or load balancing, then the data sets must be held in a shared folder that is accessible to all SAS Federation Servers. This typically requires SAS Federation Server to have Read access to this shared folder. Because SAS data sets do not concurrent access for writing to them, they are commonly used as Read-only. It is possible to write to SAS data sets through the SAS Federation Server by disabling concurrent access. However, this practice is not recommended because of the large performance penalty that it carries. This is done by limiting the topology to include a single SAS Federation Server and a single engine node, and then setting the size of the connection pool for the resource to 1. Reducing the number of connections reduces the number of threads for this connection and affects throughput for this resource. For applications that must write data, it is strongly recommended to use a relational database that s concurrent writes. This includes usages like logging, as well as reading and writing business data. SAS data sets can also be used to hold DS2 activity code and score code. These are read by SAS Federation Server when they are first referenced by a decision flow. As mentioned earlier, for configurations using multiple SAS Federation Servers, the data sets must be held in a shared folder accessible by all SAS Federation Servers.

Using SQLSTMT in Real-Time Applications Overview This section describes how best to take advantage of the SQLSTMT package, which first became available with SAS Federation Server 3.2. In addition to the SQLSTMT package, several other noteworthy performance improvements became available with SAS Federation Server 4.1: n Memory management improvements

294 Chapter 8 / Managing the Environment n Greater stability, as code base closely matches the SAS 9.4 DS2 code base n Access to MDS, an in-memory data store

It is advantageous to use SQLSTMT rather than the hash object, for the following reasons: n SQLSTMT allows a query to be prepared once and executed many times.

The hash object must prepare the query each time it is executed. It is a best practice to use a single SQLSTMT to prepare a query once and execute it many times rather than repeatedly calling SQLSTMT. Repeatedly calling SQLSTMT unnecessarily uses resources to repeatedly create, prepare, execute, and destroy the query. For information about how to specify the values, see the examples that follow. If you need to write to multiple schemas, create a separate SQLSTMT for each schema rather than ing the schema name to SQLSTMT. The following example illustrates how the SQLSTMT package can facilitate updating a data set in one database based on the values in another data set in a second database: libname db1 odbc =XXXX pw=XXXX dsn=exadat; libname db2 './base'; PROC DS2; data _null_; declare double x y; method run(); dcl package sqlstmt stmt1('select x,y from db1.dataset1'); dcl package sqlstmt stmt2('update db2.dataset2 set y=? where x=?', [y x]); stmt1.execute(); stmt1.bindResults([x y]); do while (stmt1.fetch() = 0); stmt2.execute(); end; end; enddata; RUN; QUIT;

This example code performs the following actions: o

stmt1 queries for all the x and y columns from the ORACLE table db1.dataset1

o

for each rowset in the result set from db1.dataset1, stmt2 performs the following actions: n

finds the rows in BASE table db2.dataset2 that have the same x column values as the x value read from db1.dataset1

n

updates the BASE table db2.dataset2 y column values of the found rows so that is the same as the y value that is read from db1.dataset1

n SQLSTMT binds parameters, which is essential to quick execution. n SQLSTMT s inserts, updates, selects, and other complex SQL

operations.


295

To use the SQLSTMT package, perform the following steps: 1

Declare the package instance as a package-level variable (before the first method declaration of your DS2 package).

2

Execute the package from a method.

3 In cases of select statements, fetch the returned data.

Because you used a package-level variable to hold the SQLSTMT instance, it is not destroyed when your method returns.

Example 1: SQL Select Statement with Bound Variables This example assumes the existence of a catalog called oraSource, with a schema called mySchema, and a table called testable. The table contains three columns: myInt of type bigint, myString of type varchar, and myFloat of type double. This example binds the input parameter and the result set values to package variables. It should be noted that, when binding a variable to an SQLSTMT package, a package-level variable must be used. This is a best practice, as it avoids making an extra copy of the variables, unlike when using the SET and Get method, which is described below. Binding becomes especially important where large string variables are involved. See the inline comments for more details. package example1 /overwrite=yes; /* Note: All variables used as bound parameter variables must be package level variables. */ /* A package level variable is used to hold the customer ID that is bound to the select statement. */ dcl bigint _custId; /* Package level variables are used to bind the result set data. */ dcl bigint _myInt; dcl varchar(255) _myString; dcl double _myFloat; /* A package level variable that gets prepared once when the package instance is created. */ dcl package SQLSTMT _selectData('SELECT myInt, myString, myFloat FROM oraSource.mySchema.testTable WHERE custId=?', [_custId]);

/* An execute method is called from the middle tier. */ method execute(bigint customerID); /* An integer variable is used to hold the return code from the function executions. */ dcl int rc; /* Set the bound parameter to the value of customer ID ed in from the middle tier. */ _custId = customerID; /* Execute the select statement. */ rc = _selectData.execute();


/* If rc equals 1, then there was an error executing. */ /* This should be logged and the method should return. */ if (rc = 1) then do; /* Log an error message. */ return; end; /* Bind the result set columns. */ rc = _selectData.bindresults([_myInt, _myString, _myFloat]); /* If rc equals 1, then there was an error binding data. */ /* This should be logged and the method should return. */ if (rc = 1) then do; /* Log an error message. */ return; end; /* Fetch the first row from the result set. */ rc = _selectData.fetch(); /* If rc equals 1, then there was an error fetching data. */ /* This should be logged and the method should return. */ if (rc = 1) then do; /* Log an error message. */ return; end; /* A return code of 2 indicates that there is no more data. */ /* In the result set, while there is data, process it */ do while(rc ~= 2); /* Do something with the data. */ /* Fetch the next row from the result set. */ rc = _selectData.fetch(); end; end; endpackage; run;

Example 2: SQL Select Statement without a Bound Variable This example assumes the existence of a catalog called oraSource, with a schema called mySchema, and a table called testable. The table contains three columns: myInt of type bigint, myString of type varchar, and myFloat of type double. In this example, set and get methods are used to access parameters and result set data. See the inline comments for more details. package example2 /overwrite=yes; /* A package level variable that gets prepared once when the package instance is created. */ dcl package SQLSTMT _selectData('SELECT myInt, myString, myFloat FROM oraSource.mySchema.testTable WHERE custId=?');


297

/* Execute the method called from the middle tier. */ method execute(bigint customerID); /* An intger variable is used to hold the return code from function executions. */ dcl int rc; /* Local variables to hold data from a single row of the result set. */ dcl bigint myInt; dcl varchar(255) myString; dcl double myFloat; /* Set the parameter to the value of customer ID ed in from the middle tier. */ _selectData.SETBIGINT(1, customerID); /* Execute the select statement. */ rc = _selectData.execute(); /* If rc equals 1, then there was an error executing. */ /* This should be logged and the method should return. if (rc = 1) then do; /* Log an error message. */ return; end;

*/

/* Fetch the first row from the result set. */ rc = _selectData.fetch(); /* If rc equals 1, then there was an error executing. */ /* This should be logged and the method should return. if (rc = 1) then do; /* Log an error message. */ return; end;

*/

/* A return code of 2 indicates that there is no more data. */ /* In the result set, while there is data, process it. */ do while(rc ~= 2); myInt = _selectData.GETBIGINT(1); myString = _selectData.GETVARCHAR(2); myFloat = _selectData.GETDOUBLE(3); /* Do something with the data. */ /* Fetch the next row from the result set. */ rc = _selectData.fetch(); end; end; endpackage; run;

Example 3: SQL Insert Statement Using Bound Parameters This example assumes the existence of a catalog called oraSource, with a schema called mySchema, and a table called testable. The table contains three columns: myInt of type bigint, myString of type varchar, and myFloat of type

298 Chapter 8 / Managing the Environment double. A single row of data is inserted based on the value ed in from the middle tier. See the inline comments for more details. package example3 /overwrite=yes; /* Note: All variables used as bound parameter variables must be package level variables. */ /* A package level variable used to hold the customer ID that is bound to the select statement. */ dcl bigint _custId; /* Package level variables used to bind the result set data */ dcl bigint _myInt; dcl varchar(255) _myString; dcl double _myFloat; /* A package level variable that gets prepared once when package instance is created. */ dcl package SQLSTMT _insertData('INSERT INTO oraSource.mySchema.testTable SET custId=?, myInt=?, myString=?, myFloat=?', [_custId, _myInt, _myString, _myFloat]);

/* An execute method is called from the middle tier. */ method execute(bigint customerID, bigint myInt, varchar(255) myString, double myFloat); /* An integer variable is used to hold the return code from function executions. */ dcl int rc; /* Set the bound parameters to the values ed in from the middle tier. */ _custId = customerID; _myInt = myInt; _myString = myString; _myFloat = myFloat; /* Execute the insert statement */ rc = _insertData.execute(); /* If rc equals 1, then there was an error executing. */ /* This should be logged and the method should return. */ if (rc = 1) then do; /* Log an error message. */ return; end; end; endpackage; run;

Suggested Initial Values for Key Tuning Elements in Systems with Heavy Workloads

299

Suggested Initial Values for Key Tuning Elements in Systems with Heavy Workloads Overview SAS Real-Time Decision Manager treatment and treatment set campaigns are the most resource intensive applications run by SAS Decision Services. These applications require comprehensive tuning of all components to achieve best performance. The settings found in this section represent reasonable initial values for treatment set applications. The settings are not necessarily appropriate for other, less resource intensive, applications. The reference application, to which the following initial tuning settings apply, includes 23 concurrent treatment campaigns in a single treatment set. Each treatment campaign calls custom DS2 code, which in turn queries an Oracle database up to six times per transaction. Note: These settings are only a suggested starting point. Additional tuning should be conducted using your specific application on your specific hardware, while simulating peak transaction volumes. Table 8.5

Reference System

Operating system

AIX 6.1

SAS Customer Intelligence or SAS RealTime Decision Manager version

6.5

SAS Decision Services version

6.4

SAS version

9.4M3

SAS Federation Server version

4.1

Number of engine servers (physical)

2

Number of SAS Federation Servers (physical)

2

Are engine and SAS Federation Server co-located or dislocated?

Dislocated, although it is recommended that the engine and SAS Federation Server be co-located.

Processor

IBM Power 7

Cores per engine server (available/used)

12/4-5

Cores per SAS Federation Server (available/used)

12/1-2

300 Chapter 8 / Managing the Environment RAM per comute server

Table 8.6

32GB

Application

Type

SAS Real-Time Decision Manager treatment sets with sort arbitration

Number of concurrent treatment campaigns

23

Number of DS2 custom packages

10

Number of I/O calls to Oracle from DS2

6 (several per transaction)

Table 8.7

Key Tuning Parameter Values

Engine JVM memory (setting/used)

16384/12288 MB

SAS Federation Server instances per compute server

1

MaxActive (SAS_Activity_Resource)

5

MaxIdle(SAS_Activity_Resource)

5

MinIdle(SAS_Activity_Resource)

5

Total number of threaded kernel worker threads

20 (5x1x2x2)

Activity execution thread pool size

1600

Table 8.8

Observed Performance

Average transaction response time

0.5 seconds

Transaction latency (service level agreement)

1-2 seconds

Observed throughput

73 transactions per second (TPS)

Peak transaction load (service level agreement)

16 transactions per second (TPS)

Best Practices for Optimum Performance Here is a list of methods to optimize performance: n Make use of the SQLSTMT package. SQLSTMT allows the use of bind

variables and package level SQLSTMT declarations, which dramatically

Tuning JVM Options

301

improves speed and resource utilization. For more information, see “Using SQLSTMT in Real-Time Applications” on page 293. Note: The SQLSTMT packages use considerable more memory than hash objects because the statements are cached for each JDBC connection. However, this memory utilization is a good trade-off for performance. n Run one SAS Federation Server per host. SAS Federation Server’s

improved internal memory management reduces threading contention and eliminates the need to run more than one instance per host. n Minimize use of the text concatenation operator, where possible, in DS2. This

operator (||) causes excessive U on the SAS Federation Server. n Increase the number of threads assigned to the activity.execution.thread.pool

from the default of 100 to 600. n Perform as much work in the database as possible. Avoid ing tables at

run time. n Always index your database tables. n If you are using the Oracle database and the rate of DS2 history activity is

high, adjust the file size of each Redo File group to 250 MB or higher or increase the number of redo log groups. The following tasks are critical to achieving best performance: n Set the appropriate number of JDBC connections to the SAS Federation

Server. n Set the appropriate number of threads available to the execution thread pool. n Write DS2 code with real-time performance in mind, using the SQLSTMT

with package level declarations and bind variables, rather than the DS2 hash object. To set the first two values appropriately, you must understand the number of activities that are being executed in each decision flow and the volume of concurrent requests.

Tuning JVM Options Tuning the JVM Memory Size You must increase the size of JVM memory when you use large SAS Information Maps. Information maps are -friendly metadata definitions of physical data sources that enable your business s to query a data warehouse in order to meet specific business needs. Large information maps can contain more than 25 million rows of data, which might require significant memory for loading and processing. You also must increase the size of JVM memory if you are using SAS Marketing Automation with SAS Real-Time Decision Manager. Set JVM options in Config\Lev1\Web\WebAppServer \SASServer6_node_number\bin\setenv.sh. You must edit the setenv.sh file for every server in a cluster.

302 Chapter 8 / Managing the Environment The recommended minimum JVM memory size is 4 GB for SASServer7 and 8 GB for SASServer6. If there are more than 200 campaigns and treatment campaigns, the recommended JVM memory size for SASServer7 is 8 GB. For more information about JVM tuning options, see SAS Web Applications: Tuning for Performance and Scalability or the Enterprise Excellence Center (EEC).

Troubleshooting JVM Out-of-Memory Error Messages You might receive the following message: Exception java.lang.OutOfMemoryError: requested size bytes JVM cannot expand its heap size if memory is completely allocated, and if swap space is not available. n Increase the available swap space by allocating more of the disk for virtual

memory. Set the values for maximum heap sizes by adding the following code to the settings for SASServer6 and SASServer7. In Config/Lev1/Web/WebAppServer/SASServer6_node_number/bin/ setenv.sh, add the following command: -Xmx8092 In Lev1/Web/WebAppServer/SASServer7_1/bin/setenv.sh, add the following command: -Xmx4096. Note: The suggested values in the maximum heap size commands might need to be modified for your environment. n Make sure that SASServer6 and SASServer7 are each allocated 4 gigabytes

of memory during installation.

Audit Services Overview Auditing is an important part of the integration of SAS applications and solutions. In its simplest form, auditing is a feature that provides a historical record of interaction with SAS applications, resources, and servers.

Events Logged The following table lists the application events that are logged by different clients of the audit service. It is a two-step process to activate and deactivate flows and change the value of global variables. The first step is to change the status of the flow in the repository. The second step is to notify the engine to update the distributed cache. The first step generates the flow activation, flow deactivation, or variable value update events. The second step generates an engine update event, if the cache is updated. Audit Event

Description

Clients

Audit Services Engine shutdown

This audit event is logged when a SAS Decision Services engine is shut down.

Engine update

This audit event is logged when the distributed cache is updated as part of engine synchronization.

303

This audit event is logged by the SAS Decision Services engine.

Note: All calls to synchronize do not necessarily update the cache. For example, the cache is not updated if the contents of the repository are the same as the cache, or if there is a problem in publishing the DS2 code to SAS Federation Server. In such cases, no event is logged. Flow activation

This audit event is logged when an activates a decision flow. The audit event is logged after the status of the decision flow is updated in the repository.

This audit event is logged by the SAS Decision Services istration API and the SAS Management Console Decision Services plug-in.

Flow deactivation

This audit event is logged when an deactivates a decision flow. The audit event is logged after the status of the decision flow is updated in the repository. A flow might be deactivated because another flow that uses the same event is activated.

This audit event is logged by the SAS Decision Services istration API and the SAS Management Console Decision Services plug-in.

Variable value updated

This audit event is logged when an changes the value of a global variable. The audit event is logged after the status of the variable is updated in the repository.

This audit event is logged by the SAS Decision Services istration API.

Consider the following items when viewing the log: n Only the engine shutdown is logged. n The SAS Management Console Decision Services plug-in does not log the

change in the global variable values. n The SAS Management Console Decision Services plug-in enables you to roll

back the activation or deactivation of a flow when it cannot notify the engine to synchronize the cache. However, in such a case, it does not record the rollback in the audit log.

304 Chapter 8 / Managing the Environment n No call to the audit log is made when a scripted activation or deactivation of a

decision flow is made using Batch Activator.

Data Logged The Web Infrastructure Platform (WIP) audit service logs the audit event data in two tables in the WIP data server. They are public.sas_audit and public.sas_audit_entry. The primary table is sas_audit. Every row of that table corresponds to an audit event. SAS Decision Services generates an audit event whenever a SAS Decision Services event, flow, activity, or global variable is created, updated, or deleted. When an audit event occurs, SAS Decision Services fills in the following fields of the audit record: Field

Description

sas_audit.audit_id

The unique ID of the record. It is also the foreign key to the sas_audit_entry table.

sas_audit.object_type_id

It contains the type ID of the object that was modified. ed values are 118 (engine), 120 (decision flow), and 122 (variable).

sas_audit.object_id

The name of the object that is affected. This is typically the name of the decision flow that is activated or deactivated, the name of the variable whose value is changed, or the name of the engine when a cache update is logged.

sas_audit._id

The ID of the who changed the object. This is significant only for the activation or deactivation of a flow or the change of the value of a variable. No ID is logged when an engine synchronizes the cache.

sas_audit.action_type_id

The ID that indicates or codifies the type of changes to the system. The allowed values are 1 (variable update), 14 (engine shutdown), 36 (flow activation), 37 (flow deactivation), and 43 (engine synchronization).

sas_audit.timestamp_dttm

The timestamp of when the event took place.

sas_audit.audit_info

Text describing the event.

sas_audit.executor_nm

The name of the application that caused the change. The values are Decision Services istration API, Decision Services Engine Server, or SAS Management Console.

Release Locked Objects

305

The sas_audit_entry table contains the additional information for certain types of audit events, such as engine synchronization and variable value update. It contains two fields that are significant to SAS Decision Services: sas_audit_entry.property_nm and sas_audit_entry.new_value_txt. These fields are used in conjunction to describe additional information about the event. Here are the possible values for engine synchronization: n property_nm contains RTDMFlow, and new_value_txt contains the name of

the flow that is loaded in the cache. n property_nm contains RTDMVariable, and new_value_txt contains the name

of the variable that is loaded in the cache. n property_nm contains the name of the global variable that is loaded in the

cache, and new_value_txt contains the value of the variable. For array type variables, there are multiple rows, each containing one array element value. For variable value updates, property_nm contains value, and new_value_txt contains the value of the variable. For array type variables, there are multiple rows, each containing one array element value.

Release Locked Objects In some circumstances, you might not be able to edit an object such as a campaign even if you have Edit permission. To unlock an object so that you can edit it, select the Locks category in the istration workspace. Figure 8.10

Locks

Only those objects that you have permission to view or edit are displayed. You must have Edit permission in order to release a locked object. Select the object that you want to release and click to be able to edit the object. After an object is released, any changes to the object can be saved only by selecting Save as.


307

Appendix 1 Troubleshooting Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Problem Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Typical Troubleshooting Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Review the Error Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Review the SASCustIntelCore6.x.log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Review the SASCustIntelStudio6x.log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Review Other Logs and Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Review Possible Resource Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Troubleshooting Validation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Checking Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Common Diagnostic Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 Common Sources of Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Locked Asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 Library Reference That Was Not Correctly Defined . . . . . . . . . . . . . . . . . . . . . . . . 312 Campaign Designers Close SAS Customer Intelligence in the Middle of a Process That They Have Initiated . . . . . . . . . . . . . . . . . . . . . . . . 313 Stored Process Server Error in SASCustIntelCore6.x.log . . . . . . . . . . . . . . . . . . . 313 DS2 Data Type PACKAGE Hash Not ed . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 Errors in Model Scoring Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 DS2 Code Differences between SAS Federation Server and Base SAS . . . . . 315 Custom DS2 Code Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 DS2 Data Type Not ed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Changes to Event Time-out Values Do Not Display . . . . . . . . . . . . . . . . . . . . . . . . 318 Queries to Database Dictionary Tables Time Out . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Errors with Null Numeric Input Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 StackOverflowError After Activating a Campaign . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Activity Code Not Published . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Event Time-out Changes Do Not Take Effect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 Components Not Receiving Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 Invalid License Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Test Run-Time Server Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Error Codes for the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 Logs for Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 Design Environment and Operational Environment Logs in SAS Customer Intelligence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

308 Appendix 1 / Troubleshooting Design Environment and Operational Environment Logs in SAS Decision Services, SAS Real-Time Decision Manager, and SAS Federation Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Customizing Logs for Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Other Logs and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Troubleshooting in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Configuring the Logging Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Configure Logging for DS2 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Enabling Logging of SAS Real-Time Decision Manager SOAP Messages . . . 334 Configuring Logging Settings in JDBC Database I/O . . . . . . . . . . . . . . . . . . . . . . . 334 Updating Date, Time Zone, and Locale Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Updating the Date, Datetime, Time Zone, and Locale Settings . . . . . . . . . . . . . . 335 Updating the Locale Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 ing SAS Technical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Initial Message to SAS Technical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Gathering Logs to Send to SAS Technical . . . . . . . . . . . . . . . . . . . . . . . . . 337

Overview This chapter presents a systematic approach to resolving problems in SAS RealTime Decision Manager. Problem information typically appears in log files. Begin by collecting basic information. A clear definition of the problem often makes it easier to find a solution.

Problem Definition A good problem definition includes the following information: 1

What is the exact sequence of steps that produced the problem?

2

What are you seeing (or not seeing) in the logs or in the results that demonstrates the problem?

3 Can the problem be reliably reproduced, or is it intermittent? 4

When did this problem first occur?

5

Has the same sequence of steps been followed before without producing the problem? If so, what might have changed? a information map b

inclusion of nulls or spaces in the data

c time zone change d permissions and authorizations within SAS products, within the database,

or on an operating system directory

Typical Troubleshooting Steps

309

e

library definitions and options within the SAS Management Console Data Library Manager plug-in

f

operating system environment variables or settings, such as locale

g

changes in SAS Federation Server settings

6

Does this problem occur for all s? If not, can this ’s problem be replicated on another ’s computer?

7

What is the environment in which the problem occurs? a operating system of the compute tier, middle tier, and client tier b database type and version for the underlying data warehouse (for

example, Oracle, SQL Server) c version and hot fix level of the SAS Customer Intelligence products 8 Is the problem occurring in a development, test, or production environment? 9 How many transactions per second are being sent at the time of the

performance problem? 10 What is the expected response time under this load? 11 What is the range of response times that are you seeing under this load? 12 What steps, if any, have you taken in order to isolate the problem to a

particular component or flow? Examples are particular activities, treatments, flows, and campaigns, or particular queries to the database. When you have collected this information, you are ready to perform the following troubleshooting steps.

Typical Troubleshooting Steps Review the Error Dialog Box To review error details in the Error dialog box, perform the following steps: 1

In the Error dialog box, click Details.

2

Copy the entire error message, and paste it into a text editor. This enables you to view the full text of the error. It also enables you to send the full text of the error to SAS Technical , if necessary.

3 Record the time of the error so that you can identify any associated error

messages in the logs. 4 Use the error message and the problem description to search for known

issues in the SAS Notes at http://.sas.com/notes/index.html. You might need to try different combinations of keywords or different sections of the error message.

310 Appendix 1 / Troubleshooting

Review the SASCustIntelCore6.x.log File If the error message in the Error dialog box does not help you find the source of the problem, perform the following steps: 1 Navigate to <SASPlanName>/Lev1/Web/Logs/SASServer6_x, open the

SASCustIntelCore6.x.log file, and search for ERROR. By default, this log is located in <SASPlanName>Lev1/Web/Logs/ SASServer6_1 on the middle tier machine.

The timestamps for the log messages help identify which messages might be associated with the error dialog box. 2 If you do not find any relevant error messages in the log, then search for

WARN.

Review the SASCustIntelStudio6x.log File If the SASCustIntelCore6.x.log file does not help you find the source of the problem, perform the following steps: 1

Navigate to <SASPlanName>Lev1/Web/Logs/SASServer6_x, open the SASCustIntelStudio6.x.logfile, and search for ERROR. By default, this log is located in <SASPlanName>Lev1/Web/Logs/ SASServer6_1 on the middle tier machine.

The timestamps for the log messages help identify which messages might be associated with the error dialog box. 2 If you do not find any relevant error messages in the log, then search for

WARN.

Review Other Logs and Logging Options If the previous log files do not provide the information that you need in order to identify and correct the error, see “Logs for Troubleshooting” on page 322 and “Common Sources of Errors” on page 312.

Review Possible Resource Constraints If the problem is intermittent and does not appear to be caused by particular changes in data, then it is likely to be related to a resource constraint. To determine whether there is a resource constraint, check the following: n memory usage for the application server JVMs (SASServer7, SASServer6,

and SASServer1). For more information, see “Troubleshooting JVM Out-ofMemory Error Messages” on page 302. n U and network usage. For more information, see “Improving Performance”

on page 268. n database connections. For more information, see “JDBC Performance

Tuning” on page 286.

Troubleshooting Validation Errors

311

n stored process server connections. For more information, see “About the

SAS Stored Process Server” on page 48. n UNIX ulimit open file descriptors. Set the file descriptors to at least 20480.

Next Steps After following these steps, it still might not be clear what is causing the problem. Search for an applicable SAS Note at http://.sas.com/notes/index.html, using different combinations of keywords or error messages that you have encountered. If the solution to the problem remains unclear, review “Problem Definition” on page 308 and send a description of the problem to SAS Technical . See “ing SAS Technical ” on page 336.

Troubleshooting Validation Errors Checking Diagnostics The SAS Decision Services diagnostics pages are useful for validating your system after configuration. If errors occur when running the diagnostics pages, check the associated log for details. Table A1.1

Diagnostics Logs

Component

Diagnostics URL

Associated Log

SAS Decision Services Design middle tier

http://hostname.domain.com:port/ RTDMDesign/jsp/Diagnostics.js

<SAS_Configuration_Directory> \Web\Logs\SASServer7_N \SASDecisionServicesDesignServ er .log

SAS Decision Services Engine Server

http://hostname.domain.com:port/ RTDM/Diagnostics.jsp

<SAS_Configuration_Directory> \Web\Logs\SASServer7_N \SASDecisionServicesEngine .log

SAS Decision Services Monitor

http://hostname.domain.com:port/ DCSVMonitor/jsp/Diagnostics.jsp

<SAS_Configuration_Directory> \Web\Logs\SASServer7_N \SASDecisionServicesMonitor .log

SAS Decision Services istration API

http://hostname.domain.com:port/ SASDecisionServicesistratio n/Diagnostics.jsp

<SAS_Configuration_Directory> \Web\Logs\SASServer7_N \SASDecisionServicesistrati on .log

Common Diagnostic Errors Here are solutions for the errors that are commonly found when you run the diagnostics pages:

312 Appendix 1 / Troubleshooting Table A1.2

Diagnostic Errors

Error

Solution

The database server or SAS Federation Server is not running.

Start the server.

Invalid s are specified for the database or SAS Federation Server.

Use the Manager plug-in in SAS Management Console to update the .

The wrong JDBC driver or data source class was used for the application server.

Edit the configured data source or edit the JDBC Connection system resource that is referenced in the error message. see “System Resources” on page 119.

The wrong version of the JDBC driver or data source class was used for the application server.

Edit the configured data source or edit the JDBC Connection system resource that is referenced in the error message. For more information, see “System Resources” on page 119.

The data source name was not found or no default driver was specified in the SAS Federation Server data service.

Install the database client on the SAS Federation Server machine or define and update the ODBC system data source on the operating system.

Common Sources of Errors Often, the error message in SASCustIntelCore6.x.log provides enough information to help you find the source of the problem and correct it. Here are some of the most common errors that you might find as well as information about how to address them.

Locked Asset To address this error, release the locked object in the Locks category in the istration workspace of SAS Customer Intelligence. For more information, see SAS Real-Time Decision Manager: ’s Guide.

Library Reference That Was Not Correctly Defined To address this error: 1

Log on to SAS Management Console as an .

2 Correct the reference by going to the Data Library Manager plug-in, right-

clicking on the library in question, and selecting Properties. The library definitions that are used by SAS Customer Intelligence can be viewed in SASCustIntelCore6.x.log. Often a careful examination of the

Common Sources of Errors 313

LIBNAME statements in this log can help you pinpoint problems with reading or writing data.

Campaign Designers Close SAS Customer Intelligence in the Middle of a Process That They Have Initiated This error can cause processes not to respond on the middle tier or the compute tier. These orphaned processes might continue to consume resources. This can slow performance or even cause out-of-memory type errors. To remedy this error: 1

Close all open instances of SAS Customer Intelligence.

2 Close all SAS Business Intelligence applications. 3

Shut down the compute tier (object spawner, workspace servers, stored process servers).

4

Check for remaining SAS processes that should not be running. Kill any processes that are not responding.

5 Restart the compute tier. 6

Restart the middle tier.

Stored Process Server Error in SASCustIntelCore6.x.log Look for additional details in the Stored Process Server logs. These files are located on your SAS Stored Process Server machine at <SASPlanName>Lev1/Web/Logs/SASServer6_x. Check the three most recent SAS Stored Process Server log files. There is generally one log for each SAS Stored Process Server process.

DS2 Data Type PACKAGE Hash Not ed SAS Real-Time Decision Manager publishes DS2 code in the following ways: n The SAS activity definition is automatically generated based on DS2 code

that you enter into SAS Customer Intelligence Studio. n The DS2 code that you enter in the SAS activity window is automatically

published to the SAS Federation Server, even if you enter multiple packages. n If you enter multiple DS2 packages in the SAS Activity window, only the final

DS2 package that you enter is used to generate the SAS activity definition. All method signatures that are in the last package of your SAS activity DS2 code are used to generate the SAS activity definition. Because all methods in the last package are used, these methods must be translatable to valid SAS Decision Services data types. (For information about valid types and the translation between SAS Decision Services types and DS2 types, see “DS2 Programming” on page 165.) A DS2 package is invalid as a SAS activity if it contains a method whose signature in not translatable.

314 Appendix 1 / Troubleshooting For example, if the method in your last package for a SAS activity contains a hash in its signature, then you receive the following error message: 2013-05-29 14:26:36,834 ERROR 41a93e32544d55ca:-3454255b:13ef116bda3:-4e60 SASDSDesignRepository com.sas.rtdm.designserver.implementation.DesignServerWebserviceFactory Converting SAS Decision Services design server exception to fault.com.sas.analytics.ph.RTDMException: DS2 data type PACKAGE hash is not ed for use in a DS2 Activity method. at com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.mapDataType(DS2ActivityReader.java:129) at com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.readParameter(DS2ActivityReader.java:73) at com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.reethod(DS2ActivityReader.java:44) at com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.read(DS2ActivityReader.java:30) at com.sas.rtdm.implementation.activity.sasactivity.SASActivityGenerator.generateActivity (SASActivityGenerator.java:24) at com.sas.rtdm.designserver.implementation.DesignServerInternalImpl.generateActivityFromDS2 (DesignServerInternalImpl.java:818) at com.sas.rtdm.designserver.implementation.TranslatingDesignServerImpl.generateActivityFromDS2 (TranslatingDesignServerImpl.java:383)

To avoid this error, and to use method types other than those ed by SAS Decision Services: 1

Create a single package in which you put only the methods that you want to expose into your SAS activity.

2 Create a utility package for the rest of your methods. 3 Enter both packages in your SAS Activity window. Enter the utility package or

packages first, and then enter the package that uses the utility. The SAS activity definition generator ignores all but the last package, and the SAS activity publisher publishes all packages.

Errors in Model Scoring Code SAS Real-Time Decision Manager enables you to use a SAS Model Manager model to provide scoring within your decision campaigns. However, model scoring code that has been successfully published might still have errors that prevent using the model in a decision campaign (flow). In order to troubleshoot a model that is not returning results or that is returning incorrect results, you can perform a manual transformation of the model scoring code. This manual step enables you to replicate the conversion of model DATA step code to DS2. The end product is DS2 code. Any error messages that are generated by the conversion step are also included. To perform a manual transformation of the model scoring code, use the following pattern, substituting your paths and filenames for those in this example: proc dstrans ds_to_ds2 in='c:\dev\scoring/score.sas' outdir='c:\dev\scoring/' out='score.tspl' xml='c:\dev\scoring/score.xml' pkgargs nocomp; run;


DS2 Code Differences between SAS Federation Server and Base SAS SAS Decision Services enables you to create and use SAS DS2 packages that are compiled and run by SAS Federation Server. This functionality uses the SAS Federation Server internal copy of the SAS DS2 compiler and engine. The SAS Federation Server internal version of SAS DS2 might be slightly older than the Base SAS internal version of SAS DS2. This version difference sometimes causes confusion when you are troubleshooting, if the problem that you encounter is specific to a particular version of SAS DS2. Here are two slightly different versions of the connection arguments to PROC DS2 that you can use in order to choose which SAS DS2 compiler you use. Running the following SAS DS2 code causes the code to be compiled in Base SAS but to run on SAS Federation Server: proc ds2 nolibs conn="driver=remts;server=your-federation-server;port=21032; protocol=bridge;uid=fed;pwd=XXXXXXXX;conopts=(DSN=BASE_dsn)"; package test_ext /extension='hash' overwrite=yes; endpackage; run; quit;

Running the following SAS DS2 code causes the code to be compiled and run in the SAS Federation Server version of SAS DS2: proc ds2 nolibs NOPROMPT="driver=remts;server=your-federation-server;port=21032; protocol=bridge;uid=fed;pwd=XXXXXXXX;conopts=(driver=ds2;conopts=(DSN=BASE_DSN))"; package tap_hash /extension='hash' overwrite=yes; endpackage; run; quit;

Use the second method above when you test SAS DS2 code for use in SAS Real-Time Decision Manager (SAS Decision Services) activities.

Custom DS2 Code Processes SAS Real-Time Decision Manager executes most campaign logic on the SAS Decision Services Design Server and Engine Server middle tier applications on SASServer7. However, custom code and scoring models (that is, custom DS2 code) are run following a different process that requires several servers to communicate with each other.

Custom DS2 Code Run Process Custom DS2 code is run using the following process: 1 A campaign that contains custom DS2 code is run by the SAS Decision

Services Engine Server (in production) or the SAS Design Server (in development in SAS Customer Intelligence Studio).

316 Appendix 1 / Troubleshooting 2

When the SAS Decision Services Engine Server begins to process the custom DS2 code, it prompts SAS Federation Server to run the code.

3 SAS Federation Server executes the code and returns the results to the SAS

Decision Services Engine Server to complete the program.

Custom DS2 Code Copy Process Before the custom DS2 code can be executed on the SAS Federation Server, the custom DS2 code must be published, which means it must be moved to a location that the SAS Federation Server is aware of. This publishing step usually happens during campaign development in SAS Customer Intelligence Studio. The SAS Decision Services Engine Server triggers execution of a stored process that copies the custom DS2 code into the DS2 code repository in SAS Federation Server, which is BASE.DSN in most environments. Custom DS2 code is copied to the SAS Federation Server using the following process: 1 To publish the DS2 code, the SAS Decision Services Engine Server requires

a stored process that runs on SAS Pooled Workspace Server. Therefore, the SAS Decision Services Engine Server communicates relevant information about the custom DS2 code to the SAS Pooled Workspace Server. 2

The SAS Pooled Workspace Server sends a request to SAS Federation Server to publish the custom DS2 code.

In some instances, the SAS Pooled Workspace Server is unable to locate SAS Federation Server, which causes the SAS Decisions Services servers to return the following errors in their logs: n ERROR com.sas.rtdm.implementation.ds2.DS2Publisher -

Failed to publish DS2 code for SAS activity "{your_SAS_Node}”. n ERROR: Unable to establish connection n ERROR: Client unable to establish connection. A

connection refused usually indicates the target server is not active. Or, if active, it may be listening on a different port or service. n ERROR: Client unable to establish connection. The Bridge

Protocol Engine Socket Access Method was unable to connect to host {localhost}, port 24141. n ERROR: Client unable to establish connection. The T/IP

tSockConnect() routine failed with error 111 (The connection was refused.). n ERROR: TKTS initialization failed.

SAS Decision Services stores the location for the SAS Federation Server in the $SAS_Activity_Resource metadata object. If the SAS Federation Server is colocated with SASServer7, then the location URL in $SAS_Activity_Resource is often set to localhost. However, if the SAS Pooled Workspace Server is not also co-located with the SAS Federation Server, then the stored process cannot find a SAS Federation Server instance at localhost. To address this issue, install the SAS Pooled Workspace Server on the same computer where an instance of SAS Federation Server is installed. You can also list the explicit fully qualified domain names for all SAS Federation Server URLs in the


$SAS_Activity_Resource metadata object. However, this action causes each SAS Decision Services server to balance calls among all SAS Federation Servers, rather than calling only the local instances.

DS2 Data Type Not ed When you enter DS2 code into SAS Customer Intelligence Studio, you can enter more than one package per SAS activity. However, only the last package is associated with the SAS Real-Time Decision Manager activity that you create. The other packages are compiled, but their methods are not checked for the use of variable types that are not allowed in activity signatures. The intended functionality is that you can use the disallowed variable types, such as HASH, in these other packages. In some releases of SAS Real-Time Decision Manager, all of the packages in your activity code are checked, despite this intended functionality. The example below uses a variable of type HASH in the method signature for the first package, but the last package includes only allowed variable types: package TypesTest_util /overwrite=yes; method foo(package hash h); h.clear(); end; method do(varchar(50) s, in_out int i); i = 0; end; endpackage; run; package TypesTest /overwrite=yes; declare package TypesTest_util util(); method execute(varchar(50) s, in_out int i); util.do(s, i); end; endpackage; run;

When you run this code, you encounter an error message similar to the one below: 2013-11-11 17:28:27,331 ERROR a1a8761d15cd81f3:-69151c9a:142469a1b3a:2bcb SASDSDesignRepository com.sas.rtdm.designserver.implementation.DesignServerWebserviceFactory Converting SAS Decision Services design server exception to fault. com.sas.analytics.ph.RTDMException: DS2 data type PACKAGE hash is not ed for use in a DS2 Activity method. at com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.mapDataType(DS2ActivityRea der.java:129) at com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.readParameter(DS2ActivityR eader.java:73) at com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.reethod(DS2ActivityRead er.java:44) at

318 Appendix 1 / Troubleshooting com.sas.analytics.ph.common.exp.DS2.DS2ActivityReader.read(DS2ActivityReader.jav a:30) at com.sas.rtdm.implementation.activity.sasactivity.SASActivityGenerator.generateAc tivity(SASActivityGenerator.java:24) at com.sas.rtdm.designserver.implementation.DesignServerInternalImpl.generateActivi tyFromDS2(DesignServerInternalImpl.java:818) at com.sas.rtdm.designserver.implementation.TranslatingDesignServerImpl.generateAct ivityFromDS2(TranslatingDesignServerImpl.java:383)

In order to work around this problem, create your DS2 utility packages outside SAS Real-Time Decision Manager.

Changes to Event Time-out Values Do Not Display In the SAS Decision Services Plug-in for SAS Management Console, you can enable, disable, or modify an event time-out value for your SAS Real-Time Decision Manager campaigns. However, the change that you make is not displayed in the interface, even after you select View ► Refresh. In order to display the correct value, close the plug-in and then re-open it.

Queries to Database Dictionary Tables Time Out SQL queries in DS2 that retrieve data from database dictionary tables perform slowly when your query statement includes parameters or functions. The slow performance of these queries prevents SAS Real-Time Decision Manager DS2 from performing fast executions of decision flows. In some cases, SAS RealTime Decision Manager returns an Execution with time-out did not complete message when you query database dictionary tables from DS2 activities. For example, the following query executes especially slowly: SELECT TABLE_SCHEM, TABLE_NAME, COLUMN_NAME FROM DICTIONARY.COLUMNS WHERE TABLE_CAT=? AND UPCASE(TABLE_NAME) = ? AND UPCASE(COLUMN_NAME) = ?

In order to avoid this slow performance, follow these two guidelines when you query DBMS dictionary tables from within DS2 code: n Use literals rather than parameters in your SQL query. n Avoid using functions in the WHERE clause of your SQL query.

Errors with Null Numeric Input Values SAS Real-Time Decision Manager enables you to call external web services from within your decision campaign. You determine during design time whether each parameter that is sent to an external web service is optional or required. However, if an integer parameter is labeled as optional, then the following error message is returned when that parameter receives a null value: com.sas.analytics.ph.RTDMException: ...

Common Sources of Errors 319 System.Web.Services.Protocols.SoapException: Server was unable to read request... System.InvalidOperationException: There is an error in XML document ... System.FormatException: Input string was not in a correct format. at System.Number.StringToNumber(String str, NumberStyles options, NumberBuffer& number, NumberFormatInfo info, Boolean parseDecimal) at System.Number.ParseInt32(String s, NumberStyles style, NumberFormatInfo info) at System.Int32.Parse(String s, NumberStyles style, IFormatProvider provider) at System.Xml.XmlConvert.ToInt32(String s)

To avoid this error, substitute a predetermined value, such as 0 or -9999, for null values that are sent to an external web service.

StackOverflowError After Activating a Campaign When you activate a campaign or diagram in SAS Real-Time Decision Manager, you might see the following error message in the SAS Decision Services plug-in for SAS Management Console: ERROR com.sas.rtdm.implementation.EngineManager - Error Synchronizing cache. java.lang.StackOverflowError at java.util.HashMap.writeObject(HashMap.java:935) at sun.reflect.GeneratedMethodAccessor15.invoke(Unknown Source) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:37) ...

This problem is sometimes triggered by insufficient memory allocation in the SASServer7 JVM. If you have sufficient memory in your middle-tier computer, increase the value for the SASServer7 JVM -Xss parameter.

Activity Code Not Published SAS Real-Time Decision Manager and SAS Decision Manager use SAS Decision Services to activate and run flows (decision campaigns). When you activate a SAS Decision Services flow that contains an activity, SAS Decision Services publishes the activity code to SAS Federation Server. This publishing step is performed by a stored process that runs in the SAS Workspace Server. If the SAS Object Spawner or SAS Workspace Server are unavailable when you activate the flow, then the activity code for that flow is never published. When this problem occurs, SAS Management Console indicates that a problem was encountered on the server, but does not provide details. The flow is activated, but produces errors when it executes. The following error message is written to the SAS Decision Services Engine Server log during the publishing step: ...ERROR com.sas.rtdm.implementation.EngineManager - Error Synchronizing cache. com.sas.analytics.ph.RTDMException: com.sas.services.connection.FatalConnectionFactoryException: The application could not log on to the server "heslax3.unx.sas.com:8701". No server is available at that port on that machine. at com.sas.rtdm.implementation.ds2.WorkSpaceConnection. (WorkSpaceConnection.j ava:86) at com.sas.rtdm.implementation.ds2.DS2Publisher.submit(DS2Publisher.java:128) at com.sas.rtdm.implementation.ds2.DS2Publisher.publish(DS2Publisher.java:87) at com.sas.rtdm.implementation.ds2.DS2Publisher.publishSASActivityCode(DS2Publisher .java:166)

320 Appendix 1 / Troubleshooting at com.sas.rtdm.implementation.cache.SynchronizingCacheLoader.publishToDS2(Synchron izingCacheLoader.java:246)

To work around the issue: 1

Deactivate the flow that contains the unpublished activity.

2

Ensure that the SAS Object Spawner and SAS Workspace Server are available.

3 Reactivate the flow.

The activity is published when the flow is reactivated. SAS Decision Services attempts to publish any unpublished activity each time the SAS Decision Services Engine Server synchronizes with SAS Metadata Server.

Event Time-out Changes Do Not Take Effect The SAS Real-Time Manager event time-out can be set in the SAS Decision Services Plug-in for SAS Management Console. However, your changes to the time-out value do not take effect in this plug-in unless you perform one of the following actions: n Right-click the repository where you are making the change

(SASEngineRepository or SASDesignRepository), and select Refresh. n Collapse and re-expand the Decision Services plug-in in the Navigation

window of SAS Management Console. n Close and restart SAS Management Console.

Components Not Receiving Message In some cases, machines where SAS Real-Time Decision Manager components are installed are unable to communicate with each other. This is usually the result of restricted firewall policies. Use the following information when troubleshooting this issue. For SAS Real-Time Decision Manager, the following ports and protocols are used for communication to and from SASServer7: n SASServer6 (http, tcServer port 8580, CustIntelReporting Web services) n SASServer1 (http, JBoss port 8080, BI Web Services) n Database port(s) (per system resource) n Federation Server port(s) (for each defined SAS Federation Server)

Requests from SASServer7 at start-up use the following: n (RMI port (5090 – 5099) and Multicast address)

The Decision Services plug-in uses the following: n SASServer7 (JBoss 8680, DS Engine Server Web Service)

SAS Decision Services uses the following: n SAS Workspace Server port (8590 – 8599)


For information about the ports for the load balancer, see SAS Intelligence Platform: Middle-Tier istration Guide.

Invalid License Error After you apply a new setinit for SAS Real-Time Decision Manager, Diagnostics.jsp might return an invalid license error similar to the following. org.springframework.ws.soap.client.SoapFaultClientException: SAS Decision Services engine license is not valid. Event will not be processed. at org.springframework.ws.soap.client.core.SoapFaultMessageResolver.resolveFault(So apFaultMessageResolver.java:37) at org.springframework.ws.client.core.WebServiceTemplate.handleFault(WebServiceTemp late.java:733) at org.springframework.ws.client.core.WebServiceTemplate.doSendAndReceive(WebServic eTemplate.java:559) at org.springframework.ws.client.core.WebServiceTemplate.sendAndReceive(WebServiceT emplate.java:496) at org.springframework.ws.client.core.WebServiceTemplate.marshalSendAndReceive(WebS erviceTemplate.java:343) at org.springframework.ws.client.core.WebServiceTemplate.marshalSendAndReceive(WebS erviceTemplate.java:337) at com.sas.rtdm.engine.webservice.testclient.proxy.EventSoapProxy.Event(EventSoapPr oxy.java:93) at com.sas.rtdm.engine.webservice.testclient.Client.submitRequest(ClientSupp ort.java:131) at org.apache.jsp.Diagnostics_jsp._jspService(Diagnostics_jsp.java:564) at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70) at javax.servlet.http.HttpServlet.service(HttpServlet.java:803) at ...

This error occurs when the SID file is not updated on the middle tier. In order to update the SID file, run the SAS Deployment Manager on your middle tier and select Update SID File in Metadata. For more information, see SAS Intelligence Platform: Installation and Configuration Guide at http://.sas.com/ documentation/onlinedoc/intellplatform/index.html.

Test Run-Time Server Error SAS Real-Time Decision Manager enables you to test your decision campaigns in SAS Customer Intelligence Studio. This test functionality uses multiple components outside of SAS Customer Intelligence Studio in order to execute your campaign. When you renew the SAS Federation Server setinit that is included with SAS Customer Intelligence Studio, the license directory path and filename appear in the dfs_entities.dtd file in the / FederationServer/etc directory. Here is an example of a relevant entry:


Error Codes for the Common Data Model The Customer Intelligence Reporting middle-tier application generates error codes in the following ranges, Table A1.3

Error Code Ranges

Component

Error Code Range

Update History in Common Data Model

700 - 799

Publish to Common Data Model

800 - 899

Logs for Troubleshooting Design Environment and Operational Environment Logs in SAS Customer Intelligence You can often gather more detailed error information by increasing the logging level, replicating the problem, and then reviewing the recent additions to the logs. SASCustIntelCore6.x.log is often the first log for which you should try increasing the logging level. If the SASCustIntelCore6.x.log messages indicate that the problem is actually with a stored process, turn on additional logging for the SAS Stored Process Server instead. Note: After changing the log level in the SASCustIntelCore-log4j.xml file, you must restart SASServer6. When you run SAS Customer Intelligence in a production environment, logging is generally kept to a minimum in order to maximize performance. Increase the logging level only when you are troubleshooting. When you finish troubleshooting, return the server environment to the previous level of logging to avoid degrading performance. Here is information about the various types of logs. Table A1.4

SAS Customer Intelligence Core Log

Filename

SASCustIntelCore6.x.log

Location

<SASPlanName>/Lev1/Web/Logs/SASServer6_x

Log Contents

Java errors, some stored process information, LIBNAME statements that were executed. This is the primary log for SAS Customer Intelligence.

Logs for Troubleshooting How to Increase the Logging Level

323

Set the logging level on the Logging page in SAS Customer Intelligence Studio. For more information, see “Set Logging Level” on page 267. The level of logs that you can adjust on the Logging page in SAS Customer Intelligence Studio are dependent on your settings in the SASCustIntelCore-log4j.xml file. Setting logging to Medium gives you DEBUG messages. Setting logging to High gives you TRACE messages. Setting logging to Off gives neither, and gives only lower-level messages depending on the settings in the SASCustIntelCore-log4j.xml file. No matter what your logging settings are on the Logging page in SAS Customer Intelligence Studio, you see at most only the levels that you specify in the SASCustIntelCorelog4j.xml file. The TRACE level displays all the information that flows between SAS Real-Time Decision Manager (SASServer6) and SAS Decision Services. The RDMTestRunner class includes TRACE logging that shows the TestInput (what SAS Real-Time Decision Manager sends to SAS Decision Services) and TestOutput (what SAS Decision Services sends back to SAS Real-Time Decision Manager).

Table A1.5

SAS Customer Intelligence Web Client

Filename

SASCustIntelStudio6.x.log

Location

<SASPlanName>Lev1/Web/Logs/SASServer6_x

Log Contents

Errors in the communications between the SAS Customer Intelligence mid-tier and the client on the web browser.

How to Increase the Logging Level

Set the logging level in SASCustIntelStudio-log4j.xml file.

Table A1.6

SAS Customer Intelligence Reporting Client

Filename

SASCustIntelReporting6.x.log

Location

<SASPlanName>Lev1/Web/Logs/SASServer6_x

Log Contents

Information about requests to write to the common data model, if using web services to write to the common data model. If you are using DS2, then there are no log contents.


Set the logging level in SASCustIntelReporting-log4j.xml file.

Table A1.7

SAS Stored Process Server

Filename

SApp_STPServer_yyyy-mm-dd_pid.log

Location

<SASPlanName> /Lev1/Web/Logs or <SASPlanName>/ Lev1/Logs

324 Appendix 1 / Troubleshooting Log Contents

Code and results from the nodes that are executed by the SAS Stored Process Server.


See SAS Note 34114 at http://.sas.com/kb/ 34/114.html.

Table A1.8

SAS Pooled Workspace Server

Filename

SASApp_PooledWSServer_yyyy-mm-dd_pid.log

Location

<SASPlanName> /Lev1/SASApp/ PooledWorkspaceServer/Logs or <SASPlanName>/ Lev1/Logs

Log Contents

Queries that are created by nodes. Because the size of this creases quickly, enable debug logging for this log only when troubleshooting a specific problem.


See SAS Note 34567 at http://.sas.com/kb/ 34/567.html.

Design Environment and Operational Environment Logs in SAS Decision Services, SAS Real-Time Decision Manager, and SAS Federation Server Table A1.9

SAS Decision Services Design Server

Filename

SASDecisionServicesDesignServer6.x.log

Location

<SASPlanName> \Lev1\Web\Common\LogConfig

\SASDecisionServicesDesignServer-log4j.xml or <SASPlanName>\Lev1\Web\Logs\SASServer7_x

Log Contents

Errors in the communications between SAS Decision Services Design Server and other components (such as SAS Customer Intelligence Studio).


See “SAS Decision Services” on page 329.

Table A1.10 Filename

SAS Decision Services Engine Server SASDecisionServicesEngineServer6.x.log

Logs for Troubleshooting Location

325

\Lev1\Web\Common\LogConfig \SASDecisionServicesEngine-log4j.xml or <SASPlanName>\Lev1\Web\Logs\SASServer7_x

Note: The following process requires knowledge of log4j. The log file contains two appenders: LogFile and LogFile2. All loggers are configured to use LogFile, which is a rolling file appender that rolls over everyday. In some situations, such as during system debugging, large amounts of log messages might be written that can make the log file too large. When the log messages are too sparse, it might be convenient to collect the log over multiple days in a single file for troubleshooting or submitting to technical . In these situations, it is convenient to use a rolling file appender that rolls over based on size. The Logfile2 appender is provided as a convenience. It rolls over every 100MB. To use the LogFile2 appender, edit the log4j configuration file and modify the logger definitions to use the LogFile2 appender. Log Contents

Errors in communication between SAS Decision Services Engine Server and customer channels such as the call center or the ATM.


See “SAS Decision Services” on page 329.

Table A1.11


Filename

SASFederationServer.x.log

Location

\SASHome\SASFederationServer\4.x\etc \dfs_log.xml

Log Contents

SAS Federation Server events, including system -specific events, application-specific events, server top-level object run-time and interface events, session object run-time and interface events, connection object-run time and interface events, statement object-run time and interface events, and general application independent events.


Set the logging level in the dfs_log.xml configuration file, located in the /etc directory of the installation path.

Customizing Logs for Troubleshooting Synchronous and Asynchronous Appenders By default, the SAS Customer Intelligence Core middle-tier application uses a synchronous appender to append new information to a log. In some situations, you might want to use an asynchronous appender instead of, or in addition to, the synchronous appender.

326 Appendix 1 / Troubleshooting Here is an example of a synchronous appender: <param name="datePattern" value="'.'yyyy-MM-dd"/> <param name="append" value="true"/> <param name="file" value="${config.lev.web.appserver.logs.dir} /SASCustIntelCore6.3.log"/> <param name="ConversionPattern" value="%d{ISO8601} %p [%X{sas.session.id}] [%X{sas..name}] [%X{sas.local.session.id}] %c{1} %m %n"/>

Here is an example of an asynchronous appender: <param name="BufferSize" value="100000"/> <param name="Blocking" value="false"/>

SAS Customer Intelligence Reporting Messages Concerning Missing Business Context Data By default, the SASCustIntelReporting6.x.log contains messages about missing business context data. These messages are not needed. You can prevent these messages from appearing by making these changes to the configuration file <SASPlanName>\Lev1\Web\Common\LogConfig \SASCustIntelReporting-log4j.xml:

TIP Because it is preferable to use DS2 to insert the data into the common

data model, you will not be using SAS Customer Intelligence Reporting and therefore you will refer to the SAS Decision Services log or the SAS Federation Server log, and not the SASCustIntelReporting6.x.log.

Logs for Troubleshooting

327

Other Logs and Files If you find that you need more information than is available in the logs above, the following logs and files might provide more details: n SAS Metadata Server log n event log from the Windows operating system n database logs n installation and configuration logs

See SAS Note 49799 at http://.sas.com/kb/49/799.html. n the hosts file

The hosts file on Windows is located in either C:\WINNT \system32\drivers\etc or C:\Windows\system32\drivers\etc. n SAS Decisions Services audit log

This log contains messages that indicate changes to components such as flows, global variables, and the starting and stopping of the SAS Decisions Services Engine. Note: Messages that indicate that SAS Real-Time Decision Management is unable to write to the database are acceptable. By default, the database is not used. To configure this log, perform the following steps: 1 Start SAS Management Console. 2

Click the Folders tab, and then select System  Applications  SAS Decision Services  Decision Services 6.4  SASDSDesignRepository.

3

In right , right-click $Audit_Log_JDBCConnectionResource, and then select Edit System Resource. For information about editing the system resource, see “System Resources” on page 119.

n SAS Decisions Services log

This log contains messages used for monitoring performance and troubleshooting. These messages include such information as the values of process variables before and after each activity, and the path followed during event execution. Note: By default, this log is disabled because of its impact on performance. After the SAS Decision Services Engine is restarted, the log is disabled. To disable the log, perform the following steps: 1

Start SAS Management Console.

2

Click the Plug-ins tab.

3 Right-click Decision Service Manager  SAS Decision Services servers  SASDSEngineServices, and then select ister.

The ister Server Settings dialog box appears. 4 Clear Enable logging.


Troubleshooting in a Clustered Environment Logs for SAS Intelligence Platform services such as SAS Visual Analytics might not be stored on the same middle-tier node where the session occurred. These logs are not assigned to a particular node and can be on any node in the server cluster.

Configuring the Logging Levels SAS Customer Intelligence The trace level for logging is set on the Environment Variables page in SAS Customer Intelligence. For more information, see “Set Logging Level” on page 267.

SAS Federation Server To troubleshoot SAS Real-Time Decision Manager DS2 Activities, you can change the logging configuration in the SAS Federation Server that executes the activities. To set the logging level to trace, perform the following steps: 1 Back up the SAS Federation Server logging configuration file: Program

Files\SASHome\SASFederationServer\4.1\etc\dfs_log.xml 2 Add the appender below to the dfs_log.xml file: <param name="Append" value="true"/> <param name="ImmediateFlush" value="true"/> <param name="fileNamePattern" value="C:\Program Files\DataFlux\FedServer\server1\var\log\SASDS_%d_%S{pid}.log"/> <param name="HeaderPattern" value="Host: '%S{hostname}', OS: '%S{os_family}', Release: '%S{os_release}', SAS Version: '%S{sup_ver_long2}', Command: '%S{startup_cmd}'"/> <param name="ConversionPattern" value="%d %-5p [%t] %c %X{Client.ID}:%u - %m"/> 3 Change the directory path for the fileNamePattern parameter in the appender

to reflect your environment's directory structure. 4 Add the decision services application logger to the dfs_log.xml file:

5 Save the dfs_log.xml file, and restart the SAS Federation Server.


329

SAS Decision Services SAS Real-Time Decision Manager executes campaigns in the SAS Decision Services design server and engine server middle-tier applications. For optimal performance, logging levels for these applications must remain low. However, there are troubleshooting situations that require increased logging levels. Use the Loggers.jsp file to specify logging levels and logging contexts without the need to restart the application. On the design server, Loggers.jsp is at http://your-machine:8680/ RTDMDesign/jsp/Loggers.jsp. On the engine server, Loggers.jsp is at http://your-machine:8680/RTDM/ Loggers.jsp. Return logging levels to their original state when you have replicated the problem and collected the logging information. Any amount of increased logging degrades performance significantly. A partial list of available logging contexts appears below. Figure A1.1

Examples of Available Logging Contexts

The SAS Customer Intelligence Core middle-tier application uses a synchronous log appender by default. If CI Core performance is critical and if the logging level adversely affects performance, use an asynchronous appender instead of, or in addition to, the synchronous appender. Here is an example of a logging configuration that uses both appenders.


<param name="datePattern" value="'.'yyyy-MM-dd"/> <param name="append" value="true"/> <param name="file" value="${config.lev.web.appserver.logs.dir}/SASCustIntelCore6.4.log"/> <param name="ConversionPattern" value="%d{ISO8601} %p [%X{sas.session.id}] [%X{sas..name}] [%X{sas.local.session.id}] %c{1} %m %n"/> <param name="BufferSize" value="100000"/> <param name="Blocking" value="false"/>

<priority value="ERROR"/>

Configure Logging for DS2 Debugging SAS Logger Configuration /sas/dev/mva-v940/tkeds/misc/tkeds.l4s is an example of a logging configuration file. It enables all DS2 (and tkeds) loggers at the trace level and logs that supply information to the file l4s.filename.out. To use this logging configuration file, enter the following: sdssas test.sas -log test.log -logconfigloc tkeds.l4s

This produces the following output files: n test.log (the standard SAS log file) n l4s.test.log (the DS2/tkeds logging output file)

DS2 Logging Details (9.4M1) DS2 provides several loggers to report both configuration and run-time information. In general, info provides the minimum amount of information and debug provides most or all of the information needed to debug a field problem. The trace level provides additional detail that assists with troubleshooting, auditing, and application behavior.


331

Configuration Loggers These loggers track information as the DS2 compiler starts up, and provide context for the actual execution of the 's code. The options supplied to the DS2 compiler are displayed:

The DS2 source code that is processed by the DS2 compiler is displayed:

Note: Package source code is logged only when it is compiled. The logger does not have access to package source code during execution time. The version information for all Threaded Kernel Extensions loaded by the DS compiler is displayed:

Run-time Loggers These loggers track actual execution. Some of the tracked information is created for each row processed. Therefore, a large input data set can produce substantial amounts of data. A trace of all method calls that occur during execution is displayed:

The generated C code is displayed:

All SQL statements prepared and executed by the DS2 compiler are displayed:

The coarse timing information about the compiler pipeline is displayed:

Example: Logging All SQL Operations The following configuration file, referenced as config.l4s, instructs DS2 to log all SQL commands.

<param name="append" value="false"/> <param name="FileNamePattern" value="sql.%S{App.Log}"/>

332 Appendix 1 / Troubleshooting <param name="ConversionPattern" value="%-5p:%sn:[%c{3}]:%m"/> <param name="Append" value="false"/> <param name="ImmediateFlush" value="true"/> <param name="FileNamePattern" value="%S{App.Log}"/> <param name="ConversionPattern" value="%m"/>

In order to use this configuration file, add the following logconfigloc option to your sdssas command: % sdssas test.sas -log test.log -logconfigloc config.l4s

A file named sql.test.log is created, and contains messages similar to the following: DEBUG:00000084:[DS2.Runtime.SQL]:Found 0 NOCHANGE columns INFO :00000085:[DS2.Runtime.SQL]:0x0afce4b0:exec-direct:CREATE TABLE WORK.outp ("i" DOUBLE, "j" DOUBLE ) DEBUG:00000086:[DS2.Runtime.SQL]:0x0afce4b0:exec-direct:ed:rc=0x00000000 DEBUG:00000087:[DS2.Runtime.SQL]:Found 0 NOCHANGE columns INFO :00000088:[DS2.Runtime.SQL]:0x0afce4b0:exec-direct:SELECT * FROM WORK.outp DEBUG:00000089:[DS2.Runtime.SQL]:0x0afce4b0:exec-direct:ed:rc=0x00000000 INFO :00000095:[DS2.Runtime.SQL]:stmt=0x0afae060:prepare:SELECT * FROM WORK.outp DEBUG:00000096:[DS2.Runtime.SQL]:stmt=0x0afae060:prepare:ed:rc=0x00000000 INFO :00000097:[DS2.Runtime.SQL]:stmt=0x0afae060:execute DEBUG:00000098:[DS2.Runtime.SQL]:stmt=0x0afae060:execute:ed:rc=0x00000000

The exact content of the output file is defined by the ConversionPattern parameter of the layout within the DetailedOutput appender. The parameter is associated with the definition of the App.TableServices.DS2 logger. This parameter causes every logger in the hierarchy rooted at App.TableServices.DS2 to be logged to the same file. The additivity="false" modifier prevents the log messages from surfacing.

Tap Loggers The tap_logger is a DS2 package that is installed on SAS Federation Server as part of SAS Decision Services (SAS Real-Time Decision Manager). This utility package simplifies adding logging to your DS2 packages for activities (such as SAS process nodes). The package is similar to Log4J in that messages can be logged at different logging levels.

Add tap_logger to Your Package To add tap_logger to your package, declare a package instance of the tap_logger package so that you can log from anywhere within your package: proc ds2 nolibs conn="driver=remts;server=your_Fed_Server;port=21032;protocol=bridge; uid=;pwd=; conopts=(DSN=Fed_Server_DSN)"; package my_pkg /overwrite=yes sas_encrypt=yes; declare package tap_logger logger();


333

method echo_string(varchar(32767) in_string, in_out varchar out_string); out_string=in_string; end; endpackage; run; quit;

Add Calls to Your Logger Within your methods, you can now call your logger instance logging messages at the level that you choose. Available levels are trace, debug, info, warn, err, and fatal. proc ds2 nolibs conn="driver=remts;server=your_Fed_Server;port=21032;protocol=bridge; uid=; pwd=;conopts=(DSN=Fed_Server_DSN)"; package my_pkg /overwrite=yes sas_encrypt=yes; declare package tap_logger logger(); method echo_string(varchar(32767) in_string, in_out varchar out_string); logger.info('Executing echo_string with a value of: ' || in_string); out_string=in_string; end; endpackage; run; quit;

Modify the SAS Federation Server Log Configuration You can find the SAS Federation Server log configuration file, dfs_log.xml, in Installation-root/FederationServer/2.1/etc. TIP Save a copy of this configuration file before you edit it.

To modify the SAS Federation Server Log Configuration: 1 Add a new file appender to dfs_log.xml that is similar to the file appender

in this example: <param name="Append" value="true"/> <param name="ImmediateFlush" value="true"/> <param name="fileNamePattern" value="Installation-root\FederationServer\2.1\var\log\SASDS_%d_%S{pid}.log"/> <param name="HeaderPattern" value="Host: '%S{host-name}', OS: '%S{os-family}', Release: '%S{os-release}', SAS Version: '%S{sup_ver_long2}', Command: '%S{startup_cmd}'"/> <param name="ConversionPattern" value="%d %-5p [%t] %c %X{Client.ID}:%u - %m"/> 2

Replace Installation-root above with the path of your installation.


Search for Application message logger and add the following logger section immediately after it:

4 Restart your SAS Federation Server.

After you restart the SAS Federation Server, all messages sent to a tap_logger instance are written to the file that you specified in the file appender above.

Enabling Logging of SAS Real-Time Decision Manager SOAP Messages There are times when troubleshooting SAS Real-Time Decision Manager requires that you trace the SOAP messages that the SAS Decision Services Engine Server receives. To improve the execution speed of decision campaigns, buffering of these messages is disabled by default. This means that the payload can be read only once. If you set the logging level for these messages to trace, then the TRACE command reads the payload first, so that the engine server cannot read the payload. To trace SOAP messages, change the payloadCaching setting to true. If you use Axiom with payloadCaching set to true, then you must ensure that the java.io.tmp file points to a valid folder. (Application servers commonly define this folder as something other than the operating system's TMP folder.) If you do not enable payload caching, the following error message appears in SASDecisionServicesEngineServer.log: <soapenv:Fault> soapenv:Server Could not access header: java.util.NoSuchElementException; nested exception is org.apache.axiom.om.OMException: java.util.NoSuchElementException

Configuring Logging Settings in JDBC Database I/O To troubleshoot JDBC database I/O, your SAS Technical representative can assist you with configuring logging settings that capture information about the I/O that is being performed. These settings affect performance. Therefore, they should be enabled only during troubleshooting. When logging is set to DEBUG level, the log message contains the prepare time, the execution time, and the SQL that is used. When logging is set to TRACE level, the log message includes everything from the DEBUG message plus the values used in the JDBC call. Depending on the call, these can include input values, result values, and WHERE clause values.

Updating Date, Time Zone, and Locale Settings

335

Updating Date, Time Zone, and Locale Settings Updating the Date, Datetime, Time Zone, and Locale Settings You can update the date, datetime, and time zone settings in the following locations: n the operating system installed on SASServer6, SASServer7, and SAS

Federation Server. For more information, see the documentation for the operating system. n the JVM option for SASServer7. n SAS Federation Server. For more information, see SAS Federation Server:

’s Guide. n each database. For more information, see the documentation for the

database. CAUTION! SAS Decision Services interprets DateTime values that are stored in a database or in SAS data sets as being in the Greenwich Mean Time (GMT) time zone A default time zone (GMT) is associated with values that are read from a database because time zone information is not persisted with the data. As a best practice, always store DateTime values using the GMT time zone. This practice enables compatibility with SAS Decision Services and removes ambiguity. n SAS Customer Intelligence Studio. For more information, see SAS Real-

Time Decision Manager: ’s Guide.

Updating the Locale Setting Internationalization (also referred to as NLS, or National Language ) and locale settings refer to the characters that are used by different languages. Locale and internationalization settings apply to the following locations: n the operating system installed on SASServer6, SASServer7, and SAS

Federation Server. For more information, see the documentation for the operating system. n the JVM option for SASServer7 n SAS Federation Server. For more information, see SAS Federation Server:

’s Guide. n on each database. For more information, see the documentation for the

database.


ing SAS Technical Initial Message to SAS Technical If you are unable to find and correct the source of the problem, SAS Technical . You can open a technical track by sending email of the problem description and attachments to [email protected]. Files that are too big to email can be sent by FTP, using the instructions that are available at http:// .sas.com/kb/20/941.html. Alternatively, you can create a technical track by using the web form at http://.sas.com/ctx/form/ createForm. To help expedite the solution to your problem, include the following information in your initial message to SAS Technical : n The memory available on each of the machines in this implementation. n The number of cores (Us) are available on each of the machines in this

implementation. n If you have performed any resource monitoring, either per machine or per

process, include information about your observations. Label your observations by machine and by process, if applicable. SAS Decision Services Monitoring enables you to monitor the performance statistics of executions. For more information, see “SAS Decision Services Monitoring” on page 279. n The problem description. For more information, see “Problem Definition” on

page 308. n The time at which the logging levels were increased and the problem was re-

created. n The steps used to re-create the problem. n The text of the error in the Error dialog box. n The following logs that contain messages from the time the problem

occurred: o

SASCustIntelCore6.x.log

o

SASCustIntelStudio6.x.log

o

SASCustIntelReporting6.x.log

o

SASStoredProcessServer_yyyy-mm-dd_pid.log

o

ObjectSpawner_yyyy-mm-dd_pid.log

o

WorkspaceServer_yyyy-mm-dd_pid.log

o

SASDecisionServicesDesignServer6.x.log

o

SASDecisionServicesEngineServer6.x.log

o

SASFederationServer.x.log

o

SASContentServer9.4.log

ing SAS Technical

337

Gathering Logs to Send to SAS Technical Best Practices It is helpful to apply the following best practices when gathering logs: n Follow the steps that are presented in “Logs for Troubleshooting” on page

322. n All logs that you gather must be from the same time period. The time period

must include a time during which the problem occurred. n Include a timestamp for when the problem occurred. Ensure that the

timestamp is included in the period covered by all of the logs. n If you have it, include a timestamp for when the problem first happened. An

approximate time is acceptable. n Include a brief description of the components that are installed on each

machine. n Label all of the logs such that technical knows which machine each

log came from.

SAS Customer Intelligence Logs For problems with SAS Customer Intelligence, gather the following logs: 1 from .../Lev1/web/logs/ of the middle-tier machine, where SAS

Customer Intelligence applications are installed (for example, SASServer6): n SAS Marketing Automation Core log (for example,

SASMarketingAutomationCoreversion-number.log), also called the SAS Customer Intelligence Core later versions 2 from .../Lev1/web/logs/ of the middle-tier machine or machines, where

SAS Decision Services applications are installed (for example, SASServer7): n SAS Decision Services Design Server log (for example,

SASDecisionServicesDesignServerversion-number.log) 3 web application server log (for example, SystemOut.log) for SASServer6 4

web application server log (for example, SystemOut.log) for SASServer7

SAS Decision Services Logs For problems with SAS Decision Services, gather the following logs: 1

from .../Lev1/web/logs/ of the middle-tier machine or machines, where SAS Decision Services applications are installed (for example, SASServer7): n SAS Decision Services Design Server log (for example,

SASDecisionServicesDesignServerversion-number.log) n SAS Decision Services Engine Server log or logs (for example,

SASDecisionServicesEngineServerversion-number.log) 2

web application server log or logs (for example, SystemOut.log) for SASServer7


from the machine or machines where SAS Federation Server is installed (the dfs_*.log files in the \FederationServer\var\Logs directory or in the common \Logs directory)

DS2 Activities and Model Score Results Logs For DS2 Activities and Model Score results problems, send the logs listed above for SAS Decision Services problems and the logs from the DS2 code when run in Base SAS, if applicable.

If Unable to Gather Log Files If you are unable to gather the logs mentioned above, send all files under the following directories for each machine in the implementation. Include the timestamps for when you encountered the problem and the labels that indicate which machine each log came from. n \Lev1\Logs n \Lev1\Web\Logs n \Lev1\FederationServer\var\Logs n \Lev1\Web\WebAppServer\SASServerN_N\logs

339

Appendix 2 Common Data Model: Concepts About the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 What Is the Common Data Model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Using the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 Updating the Content of the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 341 Managing Multiple Business Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Reporting and the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Publishing and Executing Campaigns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 How the Common Data Model Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Key Tables for Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Campaigns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Cells, Packages, and Treatments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Control Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 History and Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Integration with SAS Customer Intelligence 360 . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 About Extension (_EXT) Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Purpose of _EXT Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 About Populating the _EXT Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 About History Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 The CI_ HISTORY Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 The CI_RESPONSE_HISTORY Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 The CI_PRESENTED_TREATMENT_HISTORY Table . . . . . . . . . . . . . . . . . . . . . 357 About Lookup Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

About the Common Data Model What Is the Common Data Model? The SAS Customer Intelligence Common Data Model is a common data repository of predefined data tables in a database that are used by SAS Customer Intelligence solutions, including SAS Marketing Automation and SAS Real-Time Decision Manager. The common data model stores the following information:

340 Appendix 2 / Common Data Model: Concepts n campaign metadata (campaigns, communications, marketing cells, and

treatments). This information enables marketers to keep track of what campaigns have been created. n rules tables that associate inbound rules with treatments in a

campaign, and are published to the common data model at the same time that the treatment is published. n campaign history, which includes the following:

History the record of customer touchpoints and the campaign, communication, and cell. history records all of the offers that are available to the customer. Note: To publish the history, select Update History in the Properties in a Reply node or on the Standard Reply page. Response History the direct and indirect responses from customers to communications and offers. Response history records whether the customer accepted or rejected the offer. Presented Treatment History the record of offers that are presented to the customer. For example, if three offers are available to the customer and only one of these is presented, then the presented treatment history records that one. Each treatment records the values that SAS Real-Time Decision Manager assigns to a custom response to a customer. n customer responses

All of the business contexts for your site can share a single version of the common data model. Alternatively, you can specify a separate instance of the model for each business context. For more information, see “Managing Multiple Business Contexts” on page 342. TIP Maintaining two separate common data models, one for SAS Marketing

Automation and one for SAS Real-Time Decision Manager, ensures that any batch updates made by SAS Marketing Automation do not interfere with the ability of SAS Real-Time Decision Manager to query and record history in real time. For descriptions of the tables and their columns in the common data model, see SAS Customer Intelligence Common Data Model: Data Dictionary at http:// .sas.com/documentation/solutions/ci/index.html. You must supply the following name and to view this site: Name: sas : CI123

A diagram of the model is included at the end of the data dictionary. Use the diagram to understand the relationships among the tables that comprise the model.

Using the Common Data Model There are several possible uses for the common data model: n to ensure that your interactions with returning customers are consistent. Your

organization’s customer uses campaign metadata and campaign

About the Common Data Model

341

history during future interactions with repeat customers, so that any information and offers presented are consistent with past interactions. n to assist in the self-learning process. Referring to the campaign history helps

you determine which customer type responds best to a particular offer. To learn more about self-learning, see “Self-Learner Processes” in the SAS Real-Time Decision Manager: ’s Guide. n to assist in offering customers the most appropriate staged treatments.

Staged treatments are stored in the common data model database. If a customer within a specific demographic group s your organization, you can review all of the offers for that demographic group. This enables you to decide which staged treatment is the most appropriate one for that customer, or whether you need to arbitrate to present a more suitable offer than one of the staged treatments. For more information about staged treatments, see “Enable Staging of Treatments” on page 86 or “Stage Node” in SAS Real-Time Decision Manager: ’s Guide. SAS Customer Intelligence enables you to use a single common data model for decision campaigns for SAS Real-Time Manager data and selection campaigns for SAS Marketing Automation data. To learn more about selection campaigns, see SAS Marketing Automation: 's Guide. If you are working with selection campaigns, reporting, and decision campaigns, then you can create two copies of the common data model, one for each business context. One copy is for selection campaigns and reporting, and is a batch database that holds all history. The query time for this can range from seconds to hours. The other copy is for decision campaigns, and is a real-time database that holds only recent history and that enables rapid querying within milliseconds. Because the uses for these two databases differ, the type of each database can be different. For example, the real-time database can be a Teradata database, and the batch database can be an Oracle database. Data is synchronized regularly between these different databases (hourly between real-time and batch, and daily between batch and real time).

Updating the Content of the Common Data Model Overview The common data model is typically updated when you save a campaign after the campaign has been published, or each time you execute a campaign. A campaign is not published if the publish operation is not enabled, and if the location of the data model for the respective business context is not specified. The following common data model tables are updated when a campaign is executed: n CI__HISTORY_<subject> n CI_PRESENTED_TREATMENT_HISTORY_<subject> n CI_RESPONSE_HISTORY_<subject> n CI_DYNAMIC_TREATMENT_ATTRIBUTE n CI_DYNAMIC_TREATMENT_ATTRIBUTE_EXT n CI_PACKAGE_X_TREATMENT

342 Appendix 2 / Common Data Model: Concepts n CI_TREATMENT_CHAR_UDF n CI_TREATMENT_NUM_UDF n CI_TREATMENT_DATE_UDF n CI_STAGING_DATA

Note: This table is updated only if you are using staged treatments.

Managing Multiple Business Contexts In an environment where multiple business contexts exist, you can deploy the common data model and capture data across business contexts in two ways. Note: You typically use only one business context in SAS Real-Time Decision Manager. n Specify a single instance of the common data model. Specify that all of the

business contexts point to the same reporting libref. The BUSINESS_CONTEXT field in the CI_CAMPAIGN table captures the business context that is associated with the campaign. In this pattern, all of the campaign data across the enterprise resides in the same location. n Create a separate instance of the common data model for each business

context (recommended). In this pattern, the data of a business context resides in different locations, and each instance of the data model contains only the information for a single business context.

Reporting and the Common Data Model When campaign data is published to the common data model tables, s can access this data in SAS Visual Analytics reports. In order to view these reports, the following server and libraries are required: n SAS LASR Analytic Server n LASR library n staging library

For more information about SAS Visual Analytics reports, see “Displaying Reports in the Reports Workspace” on page 195.

Publishing and Executing Campaigns A campaign can be published to the common data model in one of the following ways: n manually in SAS Customer Intelligence Studio n when the campaign is marked for deployment n running a test in Test mode n on subsequent saves if this option is set in the business context. For

information about setting the option to automatically publish a campaign each time you save it, see SAS Real-Time Decision Manager ’s Guide.

How the Common Data Model Is Organized

343

Note: This definition of “publish” differs from that used to describe writing the DS2 packages to the SAS Federation Server database that stores DS2 code in “Create a DS2 Package” on page 168. For more information, see “Saving, Publishing, and the Common Data Model” on page 373. When you publish a campaign or create a new version of the existing campaign, you create a new set of surrogate key (SK) entries in the common data model. You might create a new version of a campaign if you want a trail so that you can see each different version of a campaign, with different metadata, that is published in the common data model. SAS Customer Intelligence Studio begins using this new campaign and data model. In the common data model, all unique foreign primary keys for all common data model tables are surrogate keys. Surrogate keys store the unique code that identifies each campaign within the database. When you create a report that provides information about the common data model, it is the metadata within these surrogate keys that provides you with the information about each table in the common data model. The four report templates are as follows: Campaign Channel Report displays campaign count by channel. Campaign Status Report displays campaigns by status. Treatment Performance Report displays treatment and response counts, treatment details, campaign type, channel, and campaign export date for the specified treatment. Note: The example templates are in English only. For more information about reports and report templates, see Chapter 6, “Displaying Reports in the Reports Workspace,” on page 195.

How the Common Data Model Is Organized Overview Here are the table types in the common data model: n Campaigns. For more information, see “Campaigns” on page 344. n Communications. For more information, see “Communications” on page 345.

Note: In SAS Real-Time Decision Manager, communications tables are used to stored Reply node data. n Control Groups. For more information, see “Control Groups” on page 349. n History and responses. For more information, see “History and Responses”

on page 349. n Cells, packages, and treatments. These include rule tables, self-

learning tables, and dynamic treatment tables.see “Cell, Package, and Treatment Tables” on page 346.

344 Appendix 2 / Common Data Model: Concepts n Information imported from SAS Customer Intelligence 360. For more

information, see “Integration with SAS Customer Intelligence 360” on page 350. To implement these tables, see Appendix 3, “Implementing the Common Data Model,” on page 363.

Key Tables for Reporting Here are the key tables in the common data model that are used for reporting: n CI_CAMPAIGN and CI_CAMPAIGN_EXT. For more information, see

“Campaign Tables” on page 344. n CI_COMMUNICATION and CI_COMMUNICATION_EXT. For more

information, see “Communication Tables” on page 345. n CI_CELL_PACKAGE. For more information, see “Cell, Package, and

Treatment Tables” on page 346.

Campaigns Campaign Tables Campaign tables contain campaign information for SAS Marketing Automation and SAS Real-Time Decision Manager.

CI_CHANGE_LOG contains an audit trail that is recorded when a component (table) of a campaign is changed.

CI_CHANGE_TYPE is a reference table that contains the types of changes that are stored in the change log. This table is prepopulated when the common data model is installed.

CI_CAMPAIGN is the central table to which the other tables in the campaigns category connect. A campaign contains a planned set of one or more communications over one or more channels that are directed at a group of subjects such as customer, household, or individual.

CI_CAMPAIGN_EXT contains the additional -defined fields if the CI_CAMPAIGN table is extended in order to meet -specific requirements.

CI_CAMP_PAGE contains the checklist item for a campaign. A checklist item can be a brief, a diagram, a communication, an optimization, a schedule, creative details, or offer details.


345

CI_CAMP_PAGE_CHAR_UDF contains character -defined fields that are associated with the campaign. These fields are custom details for the campaign group checklist.

CI_CAMP_PAGE_NUM_UDF contains the numeric -defined fields that are associated with the campaign group. These fields are custom details for the campaign group checklist.

CI_CAMP_PAGE_DATE_UDF contains date -defined fields that are associated with the campaign. These fields are custom details for the campaign checklist. For information about _UDF tables, see “UDF (-Defined) Tables” on page 352.

CI_CAMPAIGN_STATUS contains the status codes and status descriptions for a campaign. This reference table is automatically populated when the common data model is installed. For default populated values, see “About Lookup Tables” on page 357.

CI_CAMPAIGN_TYPE contains the types of campaigns. This reference table is automatically populated with the values Selection and Decision when the common data model is installed.

CI_TREAT_CAMP_SET_X_CAMPAIGN is an intersection table that models the many-to-many relationship between treatments and campaigns. When a treatment campaign is removed from the treatment campaign set, a clean publish operation removes the treatment campaign from this table.

CI_TREATMENT_CAMPAIGN_SET is a set of treatment campaigns applicable only in SAS Real-Time Decision Manager campaigns. After each treatment campaign has determined the eligibility of an offer, the campaign returns the information to the treatment campaign set. The treatment campaign set arbitrates the offers and returns the best offers to the individual customers.

CI_TREAT_CAMP_SET_STATUS is a reference table that contains the status codes and descriptions for a treatment campaign set. This table is prepopulated when the common data model is installed. The supplied values are __N (Not Marked for Deployment) and __D (Marked for Deployment).

Communications Communication Tables

346 Appendix 2 / Common Data Model: Concepts Communication tables store information about SAS Real-Time Decision Manager reply nodes and SAS Marketing Automation communication nodes.

CI_COMMUNICATION contains the general descriptive information about a reply. A reply represents the delivery of a package of treatments over a channel to particular cells.

CI_COMMUNICATION_EXT contains additional -defined fields when the CI_COMMUNICATION table must be extended in order to meet -specific requirements.

CI_COMMUNICATION_STATUS is a reference table that contains the status codes and status code descriptions for a communication. For example, the status code _11 means Exported and the status code _12 means Deployed. This table is prepopulated when the common data model is installed. Additional -defined status codes can be specified. For the default values, see “About Lookup Tables” on page 357.

_UDF Tables For information about _UDF tables, see “UDF (-Defined) Tables” on page 352.

CI_CHANNEL is a reference table that contains the channels, channel codes, and channel descriptions that are typically used in a campaign. A channel represents the means of communication (such as email) between a company and targeted customers. This table is automatically populated with common channel codes. For more information, see “About Lookup Tables” on page 357.

Cells, Packages, and Treatments Cell, Package, and Treatment Tables Cell, Package, and Treatment tables are used by SAS Marketing Automation and SAS Real-Time Decision Manager.

CI_PACKAGE contains a collection of one or more treatments. A package is used as a collection point for one or more treatments. Treatments are delivered to the channel as part of a package that is associated with a campaign.

CI_CELL_PACKAGE contains columns to associate cells, communications, and treatments with a package in order to facilitate reporting. The table also includes summary counts for s and responses at a package level. The DELETED_FLG field is set to Y when an occurrence is re-executed. Both executions have the same occurrence number. The previous occurrence is


347

deleted when a new occurrence is added. The DELETED_FLG field is not set to Y when the last occurrence is deleted. The DELETED_FLG field is set to Y when the occurrence is re-executed and has a new surrogate key. The RESPONSE_TRACKING_CD code is generated by SAS Real-Time Decision Manager at time. The calling system returns the code when there is a response or a presented treatment has been confirmed.

CI_DYNAMIC_TREATMENT_ATTRIBUTE contains the associations of what dynamic treatments are part of a campaign. In dynamic treatments, values can change each time that a campaign is run. After asg a treatment to a package, the can assign values to each of the dynamic custom details in the treatment. These values can be constants (1 or ABC) or can be references to other variables (such as global variables or output variables from upstream nodes). If they are references to other variables, the values for those custom details are calculated each time the campaign is executed, and could be different each time. To place these per-execution values into the common data model, SAS Customer Intelligence generates DS2 code that inserts the dynamic values into the various treatment tables. If web services are used for history tables, stored processes are used instead of DS2 code. This table uses the response tracking code to generate a value for the CELL_PACKAGE_SK column. In a DS2 process, the must precede the writing to the table.

CI_DYNAMIC_TREATMENT_ATTR_EXT contains additional -defined fields when the CI_DYNAMIC_TREATMENT_ATTRIBUTE table must be extended in order to meet -specific requirements. For information about the limits on the number of characters in a variable, see “About Populating the _EXT Tables” on page 351.

CI_PACKAGE_X_TREATMENT is an intersection table that models the many-to-many relationship between packages and treatments. A package can have multiple treatments. A single treatment can be a part of multiple packages.

CI_TREATMENT contains the treatments that are associated with a campaign. Treatments can be combined into a package. When a business defines a treatment, that can specify whether the treatment should be static or dynamic. Static treatments are named because their values do not change as the treatment or treatments are applied throughout the execution of a campaign. The dynamic attribute of a treatment in a decision campaign can be specified as either a variable or a manually defined value.

348 Appendix 2 / Common Data Model: Concepts

CI_STAGING_DATA associates staged treatments with a business context if the common data model is used to store staged treatments.

CI__RULE is used by SAS Real-Time Decision Manager to associate inbound rules with treatments in a campaign. There can be multiple rules for a single treatment. For more information about setting rules, see SAS Real-Time Decision Manager: 's Guide.

CI__RULE_TYPE is used by SAS Real-Time Decision Manager to associate a type with each rule. The available types are s, Presentations, or Responses

CI__RULE_INTERVAL is used by SAS Real-Time Decision Manager to associate a time interval with each rule.

CI_TREATMENT_UDF_TAG contains the treatment tag (if any) that is associated with each treatment custom detail.

CI_TREATMENT_EXT contains additional -defined fields when the CI_TREATMENT table must be extended in order to meet -specific requirements.

CI_TREATMENT_CHAR_UDF contains character -defined fields that are associated with the treatment. These fields are updated when a campaign that contains a treatment with a -defined field of type char is executed. The static or default values for the custom details are written to this table during the publish of a campaign. The dynamic values for the custom details are written to the table during campaign execution.

CI_TREATMENT_NUM_UDF contains the numeric -defined fields that are associated with the treatment. These fields are updated when a campaign that contains a treatment with a -defined field of type num is executed. The static or default values for the custom details are written to this table during the publish of a campaign. The dynamic values for the custom details are written to the table during campaign execution.

CI_TREATMENT_DATE_UDF contains the date -defined fields that are associated with the treatment. These fields are updated when a campaign that contains a treatment with a -defined field of type date is executed. The static or default values for the


349

custom details are written to this table during the publish of a campaign. The dynamic values for the custom details are written to the table during campaign execution.

Control Groups Control Group Tables Control Group tables contain information about the control groups that are used for reporting in a campaign.

CI_CONTROL_GROUP_TYPE is a reference table that contains the types of control groups that are used for reporting. The supplied type is _ST for Standard. This table is prepopulated when the common data model is installed. Additional -defined types can be specified. For more information, see Table A2.11 on page 361. In the common data model, the following associations are established: n For champion/challenger settings, the champion is the control group that the

challengers are compared with. n For challenger/challenger settings, each challenger is a control group for all

the other challengers in a node, so that any two challengers can be compared with each other. To learn more about the champion and challenger control group, see “A/B Test Node” in SAS Real-Time Decision Manager: ’s Guide.

CI_CTL_GRP_CELL_X_TEST_CELL contains the intersection of a marketing cell that is being used as a control group with a marketing cell that is being used as a test cell in order to determine the performance of this control group comparison. The values for CONTROL_GROUP_CELL_SK and MARKETING_CELL_SK are added as rows in the table when a campaign is published. This table is used for holdout control groups as well as for champion/challenger and challenger/challenger control groups.

CI_MARKETING_CELL contains a grouping of subjects that are targeted by a campaign. An example of a subject is customer, household, or individual.

History and Responses CI__HISTORY contains a record of the delivery of a particular package to a particular channel for a particular subject. For more information, see “About History Tables” on page 352.


CI_PRESENTED_TREATMENT_HISTORY contains a record of the presentation of particular treatments for a particular channel for particular subjects. For more information, see “About History Tables” on page 352. This table is used in a call center where an operator presents a subset of the delivered treatments to a customer. Data in this table is used for decision campaigns (for SAS Real-Time Decision Manager data) as opposed to selection campaigns (for SAS Marketing Automation data).

CI__HISTORY_STATUS is a reference table that contains the status codes and descriptions for a history record. This table is prepopulated when the common data model is installed. Additional -defined status codes can be specified. For the default values, see “About Lookup Tables” on page 357.

CI_RESPONSE_HISTORY contains a record of the direct or inferred response to a particular treatment or package that has been made over a particular channel by a particular subject. For more information, see “About History Tables” on page 352.

CI_RESPONSE is a reference table that contains -defined response codes and their associated descriptions.

CI_RESPONSE_CHANNEL_RESPONSE is a reference table that associates the external response codes of a specific channel with internal response codes in order to facilitate the reporting of customer responses.For the default values, see “About Lookup Tables” on page 357.

CI_RESPONSE_X_CELL_PACKAGE is an intersection table that contains the valid responses for cell packages within a communication and the response types (for example, conversion responses and non-conversion responses).

CI_RESPONSE_TYPE is a reference table that contains the codes for the types of responses such as _CV (which stands for Converted) and _RS (which stands for Responded). This table is prepopulated when the common data model is installed.

Integration with SAS Customer Intelligence 360 Integration with SAS Customer Intelligence 360 Tables SAS Customer Intelligence 360 tables contain information that is imported from SAS Customer Intelligence 360.

About Extension (_EXT) Tables

351

CI_EXTERNAL_CONT_RESP_DETAIL contains details of or response impression events extracted from and response data that is imported from SAS Customer Intelligence 360.

CI_EXTERNAL_ contains summary of events extracted from data that is imported from SAS Customer Intelligence 360.

CI_EXTERNAL_RESPONSE contains summary of response events extracted from response data that is imported from SAS Customer Intelligence 360.

About Extension (_EXT) Tables Purpose of _EXT Tables Extension (_EXT) tables are typically created in order to contain any additional information that is specific to your business practices such as the metadata for campaign groups, campaigns, communications, or treatments.

About Populating the _EXT Tables Overview The _EXT tables are not initially structured and are initially empty. As part of the customizing process, you define the new column structures that you want to add to the _EXT tables. This is usually a one-time database task. When a campaign or communication is executed, those name/value pairs in the columns of a UDF table are transposed to the rows of the associated _EXT table. The rows of the _EXT tables are populated with data. The EXT table combines CHAR_UDF, NUM_UDF, and DATE_UDF tables into one table that is more efficient for reporting. For example, CI_CAMPAIGN_EXT table has one row for every campaign and is very wide with all the UDFs in the columns. UDFs that are needed for reporting are combined in the EXT tables. For example, the campaign-level UDFs that can be used for reporting from the CI_CAMPAIGN_CHAR_UDF , CI_CAMPAIGN_NUM_UDF, and CI_CAMPAIGN_DATE_UDF will be added to the CI_CAMPAIGN_EXT. Note: For list type custom details, the value, rather than the display value, is used to populate the _EXT table. The CI_DYNAMIC_TREATMENT_ATTR_EXT table is populated with the dynamic custom details from the CI_TREATMENT_*_UDF tables and the CI_TREATMENT_EXT table is populated with the static custom details from the CI_TREATMENT_*_UDF tables. Note: The value of the CI_TREATMENT_CHAR_UDF.CHAR_UDF_VAL variable is limited to 500 characters. For more information, see “Customizing the Extension (EXT) Tables” on page 370.


UDF (-Defined) Tables A UDF table exists for each data type (character, numeric, and date). When a campaign is published, a row is added to the associated UDF table for each custom detail that is defined within the campaign. For campaigns and campaign groups, views are associated with UDF tables. The following views are associated with campaign and campaign group UDF tables. Table

View

CI_CAMP_PAGE_CHAR_UDF WHERE PAGE_NM = 'Brief Custom Details'

CI_CAMPAIGN_CHAR_UDF

CI_CAMP_PAGE_NUM_UDF WHERE PAGE_NM = 'Brief Custom Details'

CI_CAMPAIGN_NUM_UDF

CI_CAMP_PAGE_DATE_UDF WHERE PAGE_NM = 'Brief Custom Details'

CI_CAMPAIGN_DATE_UDF

CI_CAMP_GRP_PAGE_CHAR_UDF WHERE PAGE_NM = 'Brief Custom Details'

CI_CAMPAIGN_GROUP_CHAR_UDF

CI_CAMP_GRP_PAGE_NUM_UDF WHERE PAGE_NM = 'Brief Custom Details'

CI_CAMPAIGN_GROUP_NUM_UDF

CI_CAMP_GRP_PAGE_DATE_UDF WHERE PAGE_NM = 'Brief Custom Details’

CI_CAMPAIGN_GROUP_DATE_UDF

About History Tables Overview The CI__HISTORY, CI_RESPONSE_HISTORY, and CI_PRESENTED_TREATMENT_HISTORY tables have the following requirements or properties: n They are deployed in the same location as the common data model. n They must be ed in the SAS Metadata Repository. n They must be included in a SAS Information Map in order to make the

history and response history data available for use. n They are typically connected to the table or tables of the primary marketing

data by an outer . n The tables contain history for SAS Marketing Automation and SAS

Real-Time Decision Manager.

About History Tables

353

For information ing global variables to control the writing of history records during testing, see “Manage Test Behavior” on page 63.

The CI_ HISTORY Table What the CI__HISTORY Table Contains The CI__HISTORY table contains the following columns: CELL_PACKAGE_SK is the primary reference key that associates the history with a cell package. _DTTM is the date and time at which the subject (such as Customer, , or Household) is ed. _DT represents the mm/dd/yyyy value of _DTTM. _HISTORY_STATUS_CD is the reference key code that associates the history with a history status. See the CI__HISTORY_STATUS table for the supplied values of the status codes. EXTERNAL__INFO_ID1 and EXTERNAL__INFO_ID2 are columns for SAS Real-Time Decision Manager processing. Note: The length of each column is 32 characters. history updates will fail if you enter more than 32 characters in the Value cell for a history variable in a Reply node and Update History is selected. Failure of the updates does not prevent the successful execution of a campaign and no error message is displayed. OPTIMIZATION_BACKFILL_FLG is a column for use by SAS Marketing Optimization. PACKAGE_HASH_VALUE contains a hash value generated to supply a single lookup value for a combination of the dynamic custom details for a package. RESPONSE_TRACKING_CD is a unique value containing the response code that is generated by SAS Marketing Automation, and that is required to be returned with response data for appropriate attribution and tracking to a particular campaign cell package. SUBJECT_ID is the primary reference key of a unique identifier such as Subject ID (for example, Customer, , or Household) that associates the CI__HISTORY table with an external table. You need to replace the placeholder value that is assigned for this column during installation with a valid key to the appropriate external table. Note: SAS Technical does not recommend adding fields to the table. If you need additional -related fields, then create a separate table and link the information to the history table by using a key.


Structure of the CI__HISTORY Table: Subject Levels Create a separate table for each subject level for which s are made. For example, a customer history table and a household history table might both need to exist when communications might be directed to the individual or to the household. A history table is required only for the potential subject levels that apply to a communication in SAS Customer Intelligence Studio. For more information, see “Update the Placeholder SUBJECT_ID Columns” on page 368. The CI__HISTORY table contains one row for each subject for each occurrence of a communication. There is a separate record in the CI__HISTORY table for each time that a selected customer is ed. Each record represents a unique combination of communication, communication occurrence, and subject (such as Customer). Note that occurrence = 1 if the communication is not a recurring communication.

The CI_RESPONSE_HISTORY Table What the CI_RESPONSE_HISTORY Table Contains The CI_RESPONSE_HISTORY table contains information about customer behavior in response to a marketing campaign. There is one row for each subject every time that a response is recorded. The CI_RESPONSE_HISTORY table contains these columns: CELL_PACKAGE_SK is the primary reference key that associates the response with a cell package. EXTERNAL_RESPONSE_INFO_ID1 and EXTERNAL_RESPONSE_INFO_ID2 contains channel-specific data that is typically the reference to external channel information such as a transaction number. INFERRED_RESPONSE_FLG is populated by an external program and is the Actual Response that an individual customer provided as a result of a (an offer or a treatment). PROCESSED_DTTM is the last date and time that a record was processed. RESPONSE_CHANNEL_CD is the reference response code that indicates the response that originates directly from the channel. This foreign key references the RESPONSE_CHANNEL_CD column in the CI_RESPONSE_CHANNEL_RESPONSE table. The RESPONSE_CHANNEL_CD column is also the role name that corresponds to the CHANNEL_CD column of the CI_CHANNEL table. RESPONSE_DT contains the MM/DD/YYYY value of RESPONSE_DTTM. RESPONSE_DTTM is a primary key that is the date and time of the response.

About History Tables

355

RESPONSE_SK is the primary reference key code that associates the response with the response code. This column refers to the CI_RESPONSE table that is a lookup table for the response codes and their descriptions. RESPONSE_TRACKING_CD is a unique value containing the response code that is generated by SAS Marketing Automation, and that is required to be returned with response data for appropriate attribution and tracking to a particular campaign cell package. RESPONSE_VALUE_AMT is a flag that indicates the type of correlated response. Valid values are Y (inferred response) and N (direct response). SUBJECT_ID is the primary reference key of a unique identifier such as Subject ID (for example, Customer, , or Household) that associates the CI_RESPONSE_HISTORY table with an external table. You must replace the placeholder value that is assigned for this column during installation with a valid key to the appropriate external table. TREATMENT_HASH_VAL contains a hash value generated to supply a single lookup value for a combination of the dynamic custom details for a package. TREATMENT_SK is the primary reference key that associates the response with a treatment.

About Types of Responses Responses occur from the sales that result from a specific marketing offer. Both direct and inferred responses can be recorded in the CI_RESPONSE_HISTORY table.

Direct Responses Direct responses are responses that are attributed to a specific direct marketing campaign. Direct responses are captured at the time of purchase by matching a promotion code or key code to the targeted customer names. The code is provided to the customer in the offer. The promotion code is returned in the response by the customer and captured at the touchpoint so that there is a direct link between the campaign and the response. The promotion code is a value that is external to SAS Customer Intelligence. Therefore, you must decide how to manage this link between the external promotion code and a campaign in SAS Customer Intelligence.

Inferred Responses Inferred responses are those responses that are indirectly attributable to a marketing campaign, as specified by the purchase behavior of a customer. For example, inferred responses might include the responses of all of the customers in the target population of direct marketing Campaign X who bought the product during the campaign. The objective of tracking the inferred responses is to measure the total potential effect of the direct marketing efforts. Both direct and inferred responses are defined by a response interval that includes a start time and an end time. Responses that are returned outside the defined response interval are not attributed to the campaign ROI. The only

356 Appendix 2 / Common Data Model: Concepts responses that do not require a response interval are specified by either triggerbased or event-based campaigns. A customer who is targeted for a campaign might respond in a number of ways. Possible types of direct and inferred responses that you might track are listed in the following table. Table A2.1

Sample Types of Responses

Response Type

Direct

Inferred

Acceptance

Provides a promotion code at the time of purchase.

Purchases without providing a promotion code (captured in billing data).

Clicks through an email to make a purchase. Spill (to a similar product in the same category)

Clicks through an email to purchase a similar product. Provides a promotion code at time of purchase and does not purchase the product that is offered, but purchases another product in the same category.

Inquiry

Provides a promotion code and asks for more information, but does not purchase. Opens and clicks through an email, but does not purchase.

Decline (often not captured)

Halo

Provides a promotion code and does not purchase either the product that is offered or a product in the same category.

Does not provide a promotion code and does not purchase the product that is offered, but purchases another product in the same category (captured in billing data).

Does not provide a promotion code and asks for more information, but does not purchase (captured in touchpoint data).

Receives an email, but does not open it.

Does not provide a promotion code and does not purchase either the product that is offered or a product in the same category. There is no record of the purchase in the billing data.

Customers who are not targeted for a campaign are not captured in history. Therefore, their responses to that campaign are not captured.

Customers who are not targeted for a campaign are not captured in history. Therefore, their responses to that campaign are not captured.

Forwards the email offer to a friend.

About Lookup Tables

357

The CI_PRESENTED_TREATMENT_HISTORY Table What the CI_PRESENTED_TREATMENT_HISTORY Table Contains The CI_PRESENTED_TREATMENT_HISTORY table contains the following columns: CELL_PACKAGE_SK is the primary reference key that associates the presented treatment history with a cell package. EXTERNAL__INFO_ID1 and EXTERNAL__INFO_ID2 are columns for SAS Real-Time Decision Manager that confirm processing. They contain channel-specific data that is typically the reference to external channel information such as a transaction number. PRESENTED_TREATMENT_DT contains the MM/DD/YYYY value of PRESENTED_TREATMENT_HIST_DTTM. PRESENTED_TREATMENT_HIST_DTTM is the primary key that contains the date and time of the presented treatment. RESPONSE_TRACKING_CD is a unique value containing the response code that is generated by SAS Marketing Automation that is required to be returned with response data for appropriate attribution and tracking to a particular campaign cell package. SUBJECT_ID is the primary reference key of a unique identifier such as Subject ID (for example, Customer, , or Household) that associates the CI_PRESENTED_TREATMENT_HISTORY table with an external table. You must replace the placeholder value that is assigned for this column during installation with a valid key to the appropriate external table. TREATMENT_HASH_VAL is a hash value that is generated to supply a single lookup value for a combination of the dynamic custom details for a treatment. The value is S or blank if the treatment is static. TREATMENT_SK is the primary reference key that associates the presented treatment history with a treatment.

About Lookup Tables Lookup tables contain information about campaigns in SAS Marketing Automation and SAS Real-Time Decision Manager. These lookup tables, also called reference tables, are prepopulated with typical industry values: n CI_CAMPAIGN_GROUP_STATUS n CI_CAMPAIGN_GROUP_TYPE n CI_CAMPAIGN_STATUS

358 Appendix 2 / Common Data Model: Concepts n CI_CAMPAIGN_TYPE n CI_CHANGE_TYPE n CI_CHANNEL n CI_COMMUNICATION_RECURR_TYPE n CI_COMMUNICATION_STATUS n CI__HISTORY_STATUS n CI_CONTROL_GROUP_TYPE n CI_RESPONSE n CI_RESPONSE_TYPE

Note: These values are supplied when the common data model is created. Here are the tables, with their prepopulated values. Your lookup tables might contain either different or additional values if they have been customized. Table A2.2

CI_CAMPAIGN_GROUP_STATUS Table: Prepopulated Values

Campaign Group Status Code

Campaign Group Status Description

__1

Not Ready

__2

Ready to Optimize

Table A2.3

CI_CAMPAIGN_GROUP_TYPE Table: Prepopulated Values

Campaign Group Type Code

Campaign Group Type Description

OI_

Inbound Optimization Group

OO_

Outbound Optimization Group

O__

Other Optimization Group

_I_

Inbound Campaign Group

_O_

Outbound Campaign Group

___

Other

Campaigns that are migrated from a previous release retain their original campaign status codes. The codes are not converted to the values in the following table. Table A2.4

CI_CAMPAIGN_STATUS Table: Prepopulated Values

Campaign Status Code

Campaign Status Description

1_1

Initiating

1_2

Initiation Complete

About Lookup Tables 1_3

Deg

1_4

Design Complete

2_1

Approval Requested

2_2

Approval Denied

2_3

Approval Approved

3_1

Ready to Execute

3_2

Scheduled

3_3

Executing

3_4

Execute Complete

3_5

Marked for Deployment

Table A2.5

CI_CAMPAIGN_TYPE Table: Prepopulated Values

Campaign Type Code

Campaign Type Description

I

Decision

O

Selection

T

Treatment

Table A2.6

CI_CHANGE_TYPE Table: Prepopulated Value

Change Type Code

Change Type Description

_NV

New Version

Table A2.7

CI_CHANNEL Table: Prepopulated Values

Channel Code

Channel Name

Channel Description

_AG

Agent

Agent channel

_AT

ATM

ATM channel

_BT

Batch

Batch channel

_CA

Calendar

Calendar channel

_CC

Call Center

Call center channel

359

360 Appendix 2 / Common Data Model: Concepts _CT

Catalog

Catalog channel

_EL

Electronic

Electronic channel

_EM

Email

Email channel

_EV

Event

Event channel

_FX

Fax

Fax channel

_GI

General insert

General insert channel

_MC

Multichannel

Multiple potential channels

_ML

Mail

Mail channel

_MP

Mobile phone

Mobile phone channel

_OP

Off the page

Off the page channel

_PA

Print Ad

Print ment channel

_PB

Point of Sale Branch

Point of Sale (POS) branch channel

_PG

Pager mail

Pager mail channel

_PH

Phone

Telephone channel

_PM

Phone mail

Phone mail channel

_RD

Radio

Radio channel

_SC

SAS Conversation Center

SAS Conversation Center channel

_SF

Point of Sale Sales Force

Point of Sale (POS) sales force channel

_SI

Statement Insert

Statement insert channel

_SM

Statement Message

Statement message channel

_SO

Social Media

Social Media channel

_SP

Sales Promo

Sales promotion channel

_TV

TV

Television channel

_WB

Web

Web channel

_WC

Web Campaign

SAS Web Analytics Campaign

About Lookup Tables

Table A2.8

CI_COMMUNICATION_RECURR_TYPE Table: Prepopulated Values

Communication Recurr Type Code

Communication Recurr Type Description

__H

hourly

__D

daily

__W

weekly

__M

monthly

__N

none

__U

unknown

Table A2.9

CI_COMMUNICATION_STATUS Table: Prepopulated Values

Communication Status Code

Communication Status Description

_11

Executed

_30

Failed

_32

Future

Table A2.10

CI__HISTORY_STATUS Table: Prepopulated Values

History Status Code

History Status Description

_11

Executed

_13

Excluded Mandatory s

_20

Control Group

_30

Failed

Table A2.11

CI_CONTROL_GROUP_TYPE Table: Prepopulated Values

Control Group Type Code

Control Group Type Description

_AU

Automatic

_CL

Challenger

_

Champion

361

362 Appendix 2 / Common Data Model: Concepts _ST

Manual Manual control groups are created by selecting the Cell represents a control group option in the Cell node.

Table A2.12

CI_RESPONSE Table: Prepopulated Values

Response Code

Response Name

_EC

Email - Clicked Link

_EO

Email - Opened

_ER

Email - Reply

Table A2.13

CI_RESPONSE_TYPE Table: Prepopulated Values

Response Type Code

Response Type Description

_CV

Converted

_RS

Responded

363

Appendix 3 Implementing the Common Data Model Implementing the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Creating the Table Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of DDL Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Find Your DDL Scripts for Creating the Common Data Model . . . . . . . . Specify Your Database Connection Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

364 364 365 366

Setting Up the History Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Overview: Setting Up the History Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Update the Placeholder SUBJECT_ID Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Customizing the Extension (EXT) Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Modify the Definition of an Extension Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 Setting Up the Lookup Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Prepopulate the Lookup Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Resolving Translated Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 ing Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Updating the Libref for the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Saving, Publishing, and the Common Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 373 About Saving versus Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Full and Incremental Publish Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Migrating Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Implementing the Common Data Model Overview This section contains the steps for creating the table structure of the common data model. The common data model is typically created as part of the SAS Customer Intelligence installation. The common data model is used by SAS Marketing Automation and SAS Real-Time Decision Manager. For conceptual information about the common data model, see Appendix 2, “Common Data Model: Concepts,” on page 339.

364 Appendix 3 / Implementing the Common Data Model To implement the common data model: 1 that the and group authorizations are specified for the s who

start the Customer Intelligence Common Web Service in order to access the metadata for the business context. For more information, see “istering Group and Role hip” on page 105. 2

Create the table structure for common data model tables in your database. For more information, see “Creating the Table Structure” on page 364.

3 Set up the history tables. For more information, see “Setting Up the History

Tables” on page 368. 4 Customize the _EXT tables. To add the -defined fields for the associated

UDF tables, For more information, see “Customizing the Extension (EXT) Tables” on page 370. 5 Set up the lookup tables. For more information, see “Setting Up the Lookup

Tables” on page 372. 6

Create the library definition for the common data model. For details, see SAS Intelligence Platform: Data istration Guide.

7

Edit your business contexts to include the location of the metadata for the common data model tables.

Note: The databases for SAS Real-Time Decision Manager and SAS Marketing Automation should be kept separate for performance reasons. The common data model for SAS Marketing Automation is optimized for batch writing. The common data model for SAS Real-Time Decision Manager might need to be optimized for smaller writes and short, real-time queries to the SLA.

Creating the Table Structure Overview of DDL Scripts SAS Customer Intelligence provides the data definition language (DDL) scripts that are contained in a program called ci_cdm_ddl_ .sas. You execute these scripts to create the column structure of the common data model tables in your SAS environment. The SAS system modifies these DDL scripts to customize some of the tables. To set up the common data model tables, open ci_cdm_ddl_ .sas (where is the database that you are using, as specified in“How to Find Your DDL Scripts for Creating the Common Data Model” on page 365). Then, follow these steps: n Customize the history tables. Scroll down to BEGIN HISTORY SECTION and

follow the instructions for modifying the history tables. see “Setting Up the History Tables” on page 368. n Customize the -defined fields for all UDF tables. Scroll down to BEGIN

DEFINED SECTION and follow the instructions for modifying the UDF tables. n Customize the extension tables:

Creating the Table Structure o

CI_CAMPAIGN_EXT

o

CI_CAMP_CHECKLIST_ITEM_EXT

o

CI_CAMPAIGN_GROUP_EXT

o

CI_CAMP_GRP_CLIST_ITEM_EXT

o

CI_COMMUNICATION_EXT

o

CI_DYNAMIC_TREATMENT_ATTR_EXT

o

CI_TREATMENT_EXT

365

Note: CI_CAMPAIGN_EXT columns that are meant to hold dates must use a database type that holds date and time. Scroll down to BEGIN EXTENSION SECTION and follow the instructions for modifying the extension tables. After customizing the ci_cdm_ddl_ .sas file, execute it via SAS to place the tables in the database.

How to Find Your DDL Scripts for Creating the Common Data Model The following table lists the name of the program that contains the DDL script for each database type: Database

Program Name

DB2

ci_cdm_ddl_db2.sas

Greenplum

ci_cdm_ddl_greenplum.sas

Netezza

ci_cdm_ddl_netezza.sas

Oracle

ci_cdm_ddl_oracle.sas

PostgreSQL

ci_cdm_ddl_postgres.sas

SQL Server on UNIX

ci_cdm_ddl_sqlserver_sqlsvr.sas

SQL Server - OLE DB Connection on Windows

ci_cdm_ddl_sqlserver_oledb.sas

SQL Server - ODBC Connection (Windows only)

ci_cdm_ddl_sqlserver_odbc.sas

Teradata

ci_cdm_ddl_teradata.sas

Find the program at the following default locations: n Under Windows: Program Files\SASHome\SASFoundation\9.4\cicsvr

\sasmisc n Under UNIX: /SASHome/SASFoundation/9.4/misc/cicsvr

366 Appendix 3 / Implementing the Common Data Model

Specify Your Database Connection Values Overview of Specifying Database Connection Values To specify the connections between your database and the common data model tables, open ci_cdm_ddl_ .sas , where is the database that you are using. For more information, see “How to Find Your DDL Scripts for Creating the Common Data Model” on page 365. Make the changes that apply for the applicable database type as follows.

DB2 Example %let = < Name>; %let = <>; %let dsn = ;

/* Other than Default */ /* DB2 */ /* DB2 Data Source */

Greenplum Example %let %let %let %let %let %let

= = db = ; server port = schema

; /* Other than Default */ ; /* Greenplum */ /* Greenplum Database */ = ; /* Greenplum Server */ ; /* Greenplum Port */ = ; /* Greenplum Schema */

Netezza Example %let %let %let %let %let

lib = ; = <>; pwd = <>; db = ; server = <server>;

/* /* /* /* /*

For example, MAREPORT Netezza Netezza Netezza Database Netezza Server

*/ */ */ */ */

Oracle Example %let path = ; %let = < Name>; %let = <>;

/* From tnsnames.ora /* Oracle /Schema /* Oracle

*/ */ */

For example, if the name is scott, the is tiger, and the Oracle TNS Entry computer is cicommon.acme.com, then your %LET statements would be similar to the following statements: %let path = cicommon.acme.com; %let = scott; %let = tiger;

If the SAS session encoding is UTF-8, the length of staged treatment names might exceed 128 bytes. In this case, there are execution errors. In order to accommodate these longer names, add a DBCONINIT option to the CONNECT

Creating the Table Structure

367

statement to specify character semantics for the Oracle database. Character semantics are specified in the following example: CONNECT TO ORACLE (=& =& PATH=&PATH DBCONINIT="begin execute immediate('ALTER SESSION SET NLS_LENGTH_SEMANTICS=CHAR');end;");

Note: For Oracle, if the common data model is in a separate database instance from the customer’s subject data (for example: customer, household, ), then the tnsnames.ora file must be updated with the new connection information about the subject data files. The tnsnames.ora file is located on the SAS computer where the Oracle client is installed.

PostgreSQL Example %let %let %let %let %let %let

server = port = ; = ; = ; database schema =

; /* Postgres Server */ /* Postgres Port */ /* Postgres /Schema */ /* Postgres */ = ; /* Postgres Database */ ; /* Postgres Schema */

Mixed case or uppercase names for tables, columns, or schemas are not ed for PostgreSQL except for table CI_STAGING_DATA. Table CI_STAGING_DATA must be uppercase.

SQL Server – Linux Example %let %let %let %let

= ; /* Other than Default */ pwd = ; /* SQL Server */ dsn = ; /* SQL Server Data Source */ schema = ; /* SQL Server Schema */

SQL Server – OLE DB Connection Example %let %let %let %let %let

= < Name>; pwd = <>; dsn = ; schema = <Schema>; catalog = ;

/* /* /* /* /*

Other than SQL Server SQL Server SQL Server SQL Server

Default Data Source Schema Catalog

*/ */ */ */ */

SQL Server – ODBC Connection Example %let %let %let %let

= pwd = dsn = schema

< Name>; <>; ; = <Schema>;

/* /* /* /*

Other than SQL Server SQL Server SQL Server

Default Data Source Schema

*/ */ */ */

If the SAS session encoding is UTF-8, replace VARCHAR with NVARCHAR throughout the file, as in the following example. CAMPAIGN_NM NVARCHAR(60) NULL , CAMPAIGN_DESC NVARCHAR(256) NULL , CAMPAIGN_FOLDER_TXT NVARCHAR(1024) NULL ,

368 Appendix 3 / Implementing the Common Data Model CAMPAIGN_OWNER_NM

NVARCHAR(60) NULL ,

Teradata Example %let %let %let %let %let

lib = = = server = database

; < Name>; <>; <Server>; = ;

/* /* /* /* /*

For example, MAREPORT Teradata Teradata Teradata Server or TDPID Teradata Database

*/ */ */ */ */

Setting Up the History Tables Overview: Setting Up the History Tables These three history tables must be created according to subject type within the environment: n CI__HISTORY records the s who are identified. For more

information, see “CI__HISTORY” on page 349. n CI_PRESENTED_TREATMENT_HISTORY records the specific treatments

that were actually presented to the consumer. This table is automatically populated by SAS Real-Time Decision Manager. For more information, see “CI_PRESENTED_TREATMENT_HISTORY” on page 350 n CI_RESPONSE_HISTORY records the responses to specific s or

presentations of treatments. For more information, see “CI_RESPONSE_HISTORY” on page 350 The following changes are required to set up these tables for subject and business context. The section of the open ci_cdm_ddl_ .sas program code for history tables appears in BEGIN HISTORY SECTION. Note: When you run this code in order to set up a demonstration, one change to this program is required: specify the customer-specific target source connection values in the %LET statements at the beginning of the program.

Update the Placeholder SUBJECT_ID Columns Placeholder Columns Each of the tables in BEGIN HISTORY SECTION by default contains the primary key column, SUBJECT_ID, that is used as a placeholder column. A history table can belong to one or more subjects, as well as to one or more business contexts. You must update SUBJECT_ID with a customer-specific subject key column or columns that typically point to an external table of custom business values.

Update a Single Subject 1 SUBJECT_ID is a placeholder column for the subjects. Replace this column

with the key column or columns of the subject or subjects. For example, if the

Setting Up the History Tables 369

subject that is referenced is Customer and if the key column is CUSTOMER_ID that is referenced as VARCHAR(10), then replace the SUBJECT_ID column with this column: CUSTOMER_ID VARCHAR(10) NOT NULL

Note: If the subject has a composite key, then the multiple columns of the composite key replace the SUBJECT_ID column. 2

Replace SUBJECT_ID column in the primary key constraint statements.

Update Multiple Subjects 1 Duplicate each of the three history tables for each subject that track history,

and assign a subject-specific name to each table. For example, if one of the multiple subjects that are referenced is Customer, then the history tables might have these names: n CI_CUST__HISTORY n CI_CUST_RESPONSE_HISTORY n CI_CUST_PRESENTED_TREAT_HIST 2

Rename the constraint names to match the new subject-specific table names.

3 Follow the same steps in “Update a Single Subject” on page 368 for the set

of tables for each subject. 4

Repeat the previous steps for each subject.

Update a Single Subject in Multiple Business Contexts A single business context requires no change other than the modifications described above for the single or multiple subject updates. If a multiple business context setup is required, you can use one of the following techniques: n Run this entire SAS program using a different schema for each business

context. Every common data model table should be duplicated for each schema. n For each schema, duplicate the three tables in the history section, once for

each subject in all business contexts, and assign an identifiable business context name to each table. If a company is divided into two separate business contexts, duplicate and name the three tables in the history section according to the corresponding business context. Here are examples: n CI_AP_CUST__HISTORY n CI_AP_CUST_RESPONSE_HISTORY n CI_AP_CUST_PRESENTED_TREAT_HIST n CI_NA_CUST__HISTORY n CI_NA_CUST_RESPONSE_HISTORY n CI_NA_CUST_PRESENTED_TREAT_HIST

370 Appendix 3 / Implementing the Common Data Model Note: Table names must conform to the restrictions (such as length and special characters) of the target data source. For example, the maximum length of a table name in Oracle is 30 characters.

Update Multiple Subjects in Multiple Business Contexts Multiple subjects within multiple business contexts can also exist. Use a naming convention to easily identify the combination of subject and business context. Here are examples: n CI_AP_CUST__HISTORY n CI_AP_CUST_RESPONSE_HISTORY n CI_AP_CUST_PRESENTED_TREAT_HIST n CI_AP_HHLD__HISTORY n CI_AP_HHLD_RESPONSE_HISTORY n CI_AP_HHLD_PRESENTED_TREAT_HIST n CI_NA_CUST__HISTORY n CI_NA_CUST_RESPONSE_HISTORY n CI_NA_CUST_PRESENTED_TREAT_HIST

Customizing the Extension (EXT) Tables Overview These steps are required in order to customize an extension table: 1 Modify the database table definition for the extension table. This step is

performed by the system DBA. 2

Identify which custom details (UDFs) are associated with which column of the extension table. This step is performed by the in SAS Management Console.

Note: -defined fields (UDFs) in the common data model are represented as custom details in SAS Customer Intelligence and in SAS Management Console.

Modify the Definition of an Extension Table Overview The extension tables contain one column by default that is a key column that is associated with a main table in the common data model. For example, the extension table, CI_CAMPAIGN_EXT, contains the single column called CAMPAIGN_SK that is a key column in the associated table, CI_CAMPAIGN. To create the new UDF columns for reporting, add a column to the extension table. Here is an example of SAS code in which a column called

Customizing the Extension (EXT) Tables

371

CAMPAIGN_ADDITIONAL_DESC is added to the CI_CAMPAIGN_EXT extension table in an Oracle database. Example: Modifying the Oracle Database Table Definition of an Extension Table /*===================================================================*/ /* Enter Customer Specific Target Source Connection Values - Oracle */ /*===================================================================*/ %let path = ; %let = < Name> ; %let = <> ;

/* From tnsnames.ora */ /* Oracle for schema */ /* Oracle */

PROC SQL NOERRORSTOP; CONNECT TO ORACLE (=& =& PATH=&PATH); EXECUTE (ALTER TABLE CI_CAMPAIGN_EXT ADD CAMPAIGN_ADDITIONAL_DESC VARCHAR (50)) BY ORACLE; DISCONNECT FROM ORACLE; QUIT;

Set Up the -Defined Fields in SAS Customer Intelligence Custom details, or -defined fields, are defined in SAS Customer Intelligence. In order to indicate that a specific UDF (-defined field) should be added to the extension table, specify the name of the column that corresponds to the custom detail. This custom detail must conform to SAS column-naming conventions. The name can contain uppercase and lowercase letters (A through Z), numeric digits (0 through 9), and underscores (_). The first character in the name must be a letter (A through Z) or an underscore. The name cannot contain blank spaces or special characters.

Populating the Extension Tables The extension tables are populated automatically when a campaign is published or a campaign is executed. Using the specific UDF tables as input, the system performs simple row-to-column mapping. One column in the extension tables is populated for each row that exists in the associated UDF tables. This example code shows the values of the specific UDF table that return a value of East. The value East is also published to the CAMPAIGN_ADDITIONAL_DESC column in the extension table. CAMPAIGN_SK = 1000000001 CHAR_UDF_NM = 'Sales Unit' CHAR_UDF_SEQ_NO = 000002 CHAR_UDF_CHECKLIST_FLG = 'N' CHAR_UDF_VAL = 'East' CHAR_EXT_COLUMN_NM = 'CAMPAIGN_ADDITIONAL_DESC' PROCESSED_DTTM = 01-APR-2013 00:00:00

372 Appendix 3 / Implementing the Common Data Model If the column does not exist in the extension table, then no error is reported. However, no data is written. You can either create campaign definitions that have extension column names before the tables are modified, or modify the tables before you create the campaign definitions.

Setting Up the Lookup Tables Prepopulate the Lookup Tables After the lookup tables for the common data model are created, you next prepopulate the lookup tables with default values. To prepopulate the lookup tables and assign start-up codes, run the ci_cdm_load_codes.sas program. Find ci_cdm_load_codes.sas at the following locations: n Under Windows: Program Files\SASHome\SASFoundation\9.4\cicsvr


Edit ci_cdm_load_codes.sas to set the correct LIBNAME for your database. The following example sets the LIBNAME for an Oracle database. %let lib= CDMLIB; LIBNAME &lib. ORACLE PATH=&path. =&. =&.;

The ci_cdm_load_codes.sas program must be run in the same session as the ci_cdm_ddl_.sas script that creates the tables in order to refer to database connection values that can be referenced. The &lib. macro variable must be set to a valid migration library. This program uses macros that are already defined in SAS server tier. The macros must be executed when the session is connected to the machine that is used with the common data model. For a list of lookup tables and their prepopulated values, see “About Lookup Tables” on page 357.

Resolving Translated Data The SASMSG function has been added to each INSERT statement in ci_cdm_ddl_ .sas to properly resolve the translated data that contains characters in Unicode escape representation. The SASHELP.ci tables that are created by SMD files contain these characters. These characters are resolved by the SASMSG function when the message text is read from the table. These characters are used in the table to enable you to store data for all languages in one SAS data set. The tables are also created in an encoding that s ASCII characters that are used in Unicode escape representation to prevent problems with data loss during transcoding. These problems can occur if the language of the locale is incompatible with the session encoding.

Saving, Publishing, and the Common Data Model

373

ing Data Sources Updating the Libref for the Common Data Model Re- the Common Data Model An ed the common data model during the installation of SAS Customer Intelligence. However, if you change the location of your common data model tables, then you must re- the common data model by updating the libref that references the common data model. For details, see SAS Intelligence Platform: Data istration Guide.

Specify the Common Data Model Library Location for a Business Context To configure a business context so that it points to the library location for the common data model, specify the data options, database options, and reporting options on the Settings tab. For more information, see SAS Real-Time Decision Manager: ’s Guide Do not specify FASTLOAD, BULKLOAD, or MULTILOAD options in the LIBNAME statement for the common data model library. Those options are available only in the bulk-load facility. For more information, see. on page 276

Saving, Publishing, and the Common Data Model About Saving versus Publishing When s publish campaign data, they populate or update the tables of the common data model. A new campaign designer saves a campaign after creating it. SAS Customer Intelligence does not automatically publish it when it is saved, because any view of the partial data, if the data were updated to the common data model, would be incorrect. The Save operation, because it does not update the common data model, also uses fewer system resources than the Publish operation. You can specify an option in SAS Customer Intelligence to publish a campaign when you save it. After all of the components of the campaign have been completed and the common data model is ready to be updated, the designer can manually publish the campaign. If the Automatically publish campaigns on subsequent save option has been set for the business context, the campaign data is published every time that the campaign is saved after the initial Publish operation. When any communication within a SAS Marketing Automation campaign is executed, the system automatically publishes the campaign. In subsequent Publish operations, the common data model is updated with any changes that were made since it was last published.

374 Appendix 3 / Implementing the Common Data Model Note: If a campaign is published, these consequences might result: n Performance is reduced during each subsequent Save operation. n If the campaign designer saves a partially completed campaign , any view of

the data in the common data model reflects this partial state. Analysts can view the reports of the campaign data from the common data model.

Full and Incremental Publish Operations A full Publish operation occurs when you first manually publish a campaign from within SAS Customer Intelligence. When you first manually publish a campaign, all publishable data is sent to the common data model. Subsequent requests to publish the campaign from within SAS Customer Intelligence result in an incremental Publish operation. An incremental Publish operation updates only those fields in the common data model that have changed or have never been published. An incremental Publish operation occurs under these conditions: n You request that a campaign be published from SAS Customer Intelligence

and the campaign has been previously published. n You mark a campaign for deployment. n You run a test in the Test interface in SAS Customer Intelligence Studio. n A previously published campaign is saved and the Automatically publish

campaigns on subsequent saves option is selected for the business context.

Migrating Tables The migration of the common data model from SAS Real-Time Decision Manager 5.4 and 5.4.1 to 6.1 and later requires the running of the ci_cdm_migrate_to_61_ .sas script. This is an in-place script that takes place in one schema or database. No migration of data from one schema or database to another schema or database is provided for in this script. You should make a complete backup version of the 5.4 common data model before you run the migration script. Within each migration script the connection values and history tables must be customized. As the script executes, there are instances in which a current 5.4 table is dropped and then re-created. In these instances a backup version of the table is created and left intact after the script completes in order to save the original data. Find the migration scripts at the following locations: n Under Windows: Program Files\SASHome\SASFoundation\9.4\cicsvr


Migrating Tables

375

In SAS Real-Time Decision Manager 6.4, a change was made in the way that treatment custom details of type Numeric Range or Date Range are published in the common data model. For information about migrating tables that contain treatment custom details to SAS Real-Time Decision Manager 6.5 from previous releases, see “Migrating Files from a Previous Release” in .

376 Appendix 3 / Implementing the Common Data Model

377

Appendix 4 Command-Line Utilities About the Command-Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Encode s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Add Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Overview of the Add Channels Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 How to Use the Add Channels Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Add Channels Utility Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 Batch Export and Import Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 Overview of the Batch Export and Import Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 How to Use the Batch Export Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 How to Use the Batch Import Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Batch Export and Import Tool Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Load Treatments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Overview of the Load Treatments Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 How to Use the Load Treatments Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Treatment Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Treatment Rules Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Treatment Custom Detail Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 Treatments to Delete Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 List Values Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Load Treatment Utility Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Write Response Definition Data to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Overview of the Response Definition Data Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 How to Use the Response Definition Data Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Response Definition Data Utility Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 Lineage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 Overview of the Lineage Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 How to Use the Lineage Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Lineage Utility Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Lineage Utility Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Lineage Utility Domain Object Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Lineage Utility Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Clean Up Production Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Overview of the Clean Up Engine Repository Utility . . . . . . . . . . . . . . . . . . . . . . . . 399 How to Use the Clean Up Engine Repository Utility . . . . . . . . . . . . . . . . . . . . . . . . 400 Use the Launcher to Complete Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Overview of the Launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Launcher Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

378 Appendix 4 / Command-Line Utilities Example of Listing Input Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Example of Publishing to a Reporting Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Example of Managing Deployment of Campaigns to Remote Environments . . 405 Example of Deploying an Activity to a Remote Environment . . . . . . . . . . . . . . . . 406 Example of Running the Self-Learner Training Stored Process . . . . . . . . . . . . . 406 Enable Logging for the Launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Troubleshooting the Most Common Launcher Errors . . . . . . . . . . . . . . . . . . . . . . . 409 List of Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

About the Command-Line Utilities The SAS Real-Time Decision Manager command-line utilities can be run in UNIX or Windows. To run the utilities, a must be able to to the middle tier machine and have a SAS ID that has the required capabilities. Here are the command-line utilities that are included in SAS Real-Time Decision Manager: Add Channels (-addchannel) enables you to create additional channel definitions. The new channels will be available in definitions that are created after the channels have been added. Load Treatments (-loadtreatments) loads internal SAS Customer Intelligence treatments from external tables. The utility reads treatments and their custom details from SAS data sets. This utility does not update treatments within campaigns. Lineage (-lineage) provides information about the lineage relationships between SAS Real-Time Decision Manager objects. Response Definition Data (-action) writes response definition surrogate key (SK) and code data to XML so that response definitions can be migrated to the next release. You execute this utility after migration if writing the response definition data was omitted from the migration process. Clean Up Engine Repository (-cleanupenginerepository) enables you to remove orphaned decision treatment campaigns and other unused objects from the production repository. You must have Write access to the repository in order to remove objects. You can also use commands to execute the batch export and import tools and to automate the promotion of SAS Real-Time Decision Manager objects between systems and repositories. You use the Launcher command-line utility (sasmalauncher.exe) to run test cases, mark campaigns for deployment, generate reports that list input variables, publish campaigns and treatment campaign sets to a reporting library, and manage remote deployments of campaigns and activities.

Add Channels

379

Encode s For greater security, encode s when you execute the command-line utilities. The parameters, including the encoded , should be ed as a single parameter to the sasciutils command. In the following example, parameters are ed to the Add Channel utility as a single parameter. echo '-addchannel -id myid - "{SAS002}3CD4EA1E0AF5A79500BC8ACC" -utilitylogfile c:/temp/cleanup.log -deldate "Jun 01, 2013"'| sasciutils

For more information about encoding s, see SAS Intelligence Platform: Migration Guide at http://.sas.com/documentation/onlinedoc/ intellplatform/tabs/install94.html.

Add Channels Overview of the Add Channels Utility The Add Channels utility enables you to create additional channel definitions. The new channels will be available in definitions that are created after the channels have been added. In order to use the Add Channels utility, you must have Write permission for all business contexts. This permission enables you to publish to the common data model and write to metadata. The sascisvc@saspw ID usually has both authorizations. To avoid performance issues, add only the channels that are actually needed. Note: Removing a custom channel is not recommended. Any campaigns that use this channel will be affected. If you need to remove a channel, SAS Technical at .sas.com.

How to Use the Add Channels Utility On Windows, the Add Channels utility is contained in the sasciutils.exe file. The typical location of this file is on the middle tier, at C:\Program Files\SASHome \SASCustomerIntelligenceUtilities\6.5. From the directory that contains the sasciutils.exe file, execute the command with the following syntax: sasciutils_console.exe -addchannel argument1 -argument2 Use the console version of the sasciutils.exe file so that debugging information is displayed in the command window. To create a sasciutils_console.exe version, make a copy of the sasciutils.exe file and rename it sasciutils_console.exe. On UNIX, the Add Channels utility is contained in the sasciutils file. The typical location is on the middle tier, at SASHome/

380 Appendix 4 / Command-Line Utilities SASCustomerIntelligenceUtilities/6.5. From the directory that contains

this file, execute the following command: sasciutils -addchannel argument1 -argument2 The command takes the following arguments: -addchannel specifies the Add Channels utility. -id is the ID of the that is used to execute the utility. This ID must have Write access to all of the business contexts that are created on the system. The sascisvc@saspw ID has this permission. - is the for the ID. -utilitylogfile specifies the location to which error messages and success messages are logged. If you specify a directory path, all directories in the path must exist before you execute the utility. -code is the channel code of the channel to be added. The code must be 1 to 3 characters in length. It must not begin with an underscore (_). The code cannot include leading or trailing blank spaces, forward slash (/) characters, backslash (\) characters, or any control characters. -name is the new name to assign to the channel code. If the name contains spaces, it must be enclosed in double quotation marks. The length of the name that you provide must be between 1 and 30 characters. Names cannot include leading or trailing blank spaces, forward slash (/) characters, backslash (\) characters, or any control characters. -skipcdm indicates that the new channel definition should not be published to the common data model. The channel is created in metadata, but no attempt is made to publish the channel to the common data model. The channel is added to the common data model after it is used in a campaign and the campaign is published. Use this option if you have several business contexts and if one or more of the associated common data models is not accessible when you execute the Add Channels utility. This channel should not be used in campaigns until the channel can be published to the common data model. If you do not use this option, and if one or more of the common data models are not accessible, publish failures will occur when you execute the Add Channels utility. The channel is added to the metadata but it is not published to the common data models that are not accessible. If errors occur, check the SASCustIntelCore6.5.log and the Stored Process Server logs for more details.

Add Channels Utility Example The following example adds a new channel with a code of D2D and name of Door to Door Solicitation. "C:\Program Files\SASHome\SASCustomerIntelligenceUtilities\6.5

Batch Export and Import Tools 381 \sasciutils_console.exe" -addChannel -id MyId - My -utilitylogfile c:/tmp/channel.log -code D2D -name "Door to Door Solicitation" -skipcdm

Batch Export and Import Tools Overview of the Batch Export and Import Tools The batch export and import tools enable you to perform promotions from an operating system command line or from a batch script. You can use these tools to export and import campaigns and other objects between folders. For information about the batch export and import tools, see the “Using the Batch Export and Import Tools” chapter in SAS Intelligence Platform: System istration Guide at SAS Intelligence Platform Product Documentation.

How to Use the Batch Export Tool The following code is an example of a Windows script that calls the batch export tools to export an object: @ECHO OFF SET SASHOME=C:\Program Files\<sas-config-dir> SET SASFOLDER=/<path-to-object> SET PROFILE=<metadata-server-connection-profile> SET CURRENT=%CD% IF %1.==. GOTO INVALID IF %2.==. GOTO INVALID CD %SASHOME%\SASPlatformObjectFramework\9.4 ExportPackage -profile "%PROFILE%" -subprop -package "%PROFILE%\%~2.spk" -log "%PROFILE%\export_%~2.log" -objects "%SASFOLDER%%~2(%~1)" %~3 %~4 %~5 %~6 %~7 %~8 %~9 GOTO END :INVALID GOTO END :END CD %CURRENT% PAUSE

Modify the code and place it in a text file named ExportCIObject.cmd. From the directory that contains this file, execute the command with the following syntax: ExportCIObject object-type object-name [-includeDep, -options]

The command takes the following arguments:

382 Appendix 4 / Command-Line Utilities object-type is the public object type. For more information, see Table A4.1 on page 382. object-name is the name of the object. -includeDep includes dependencies. -options are the other batch export tool options. After you have exported the objects, modify the substitution properties file. For more information, see SAS Intelligence Platform: System istration Guide at SAS Intelligence Platform Product Documentation. Table A4.1

Customer Intelligence Public Object Types

Public Object Type

Name

Description

CIBusinessContext

Customer Intelligence business context

An environment with associated resources that is used to partition campaign, campaign group, and treatment artifacts from one another when running on the same server

CICalculatedItem (not visible in SAS Management Console Folder view)

Customer Intelligence calculated item

A Customer Intelligence calculated item

CICampaign

Campaign

A planned set of one or more communications that are directed at a selected group of customers.

CICampaignDefinition_Selection

Selection campaign definition

A template that specifies information about the underlying structure of a selection campaign

CICampaignGroup

Campaign group

A collection of campaigns

CICampaignGroupDefinition

Campaign group definition

A template that specifies information about the underlying structure of a campaign group

CICellNode (not visible in SAS Management Console Folder view)

Campaign cell node

A node that represents a group or a subgroup that is targeted by a campaign

CICommunicationDefinition

Campaign communication definition

A template that defines information about a campaign communication, such as its export definition, code, channel, and custom details

CICommunicationNode (not visible in SAS Management Console Folder view)

Campaign communication node

A campaign node that represents a specific marketing activity or communication with the consumer

Batch Export and Import Tools 383 CICustomDetailsGroup

Custom detail group

A collection of custom details that can be reused in more than one campaign, communication, treatment, or reply

CICustomDetailsTag

Custom detail tag

A -friendly name for a custom detail

CIDiagram

Campaign diagram

A collection of nodes that make up a campaign process

CIDocument (not visible in SAS Management Console Folder view)

Campaign document

A collection of reports that summarize the information in campaigns

CIEnvironmentData

Customer Intelligence environment definition

The definition of a Customer Intelligence environment

CIExportDefinition

Campaign export definition

A collection of campaign information about the format of the data to be exported, the types of data to be exported, and other options

CIMasterSeedDefinition

Campaign seed definition

The format of a campaign seed list

CIMetadataGenerationDefinition

Customer-Intelligence-generated metadata definition

The format of customer-intelligencegenerated metadata

CINodeDefinition (not visible in SAS Management Console Folder view)

Campaign node definition

The definition of a node in a diagram

CIReportExport

Customer Intelligence report export

A Customer Intelligence report link

CIResponseDefinition

Campaign response definition

A template that defines information about a campaign response

CISeedList

Campaign seed list

A list of individuals or organizations to whom communications are sent to that the campaign communications have been processed correctly

CISurrogateKey

Customer Intelligence surrogate key definition

A map of Customer Intelligence surrogate keys

CITreatment

Campaign treatment

A type of marketing communication. A treatment includes the format, creative content, and offer

How to Use the Batch Import Tool The following code is an example of a Windows script that calls the batch import tools to import the objects in a package: @ECHO OFF

384 Appendix 4 / Command-Line Utilities

SET SASHOME=C:\Program Files\<sas-config-dir> SET SASFOLDER=<destination-pathname-of-imported-object> SET PROFILE=metadata-server-connection-profile SET CURRENT=%CD% IF %1.==. GOTO INVALID CD %SASHOME%\SASPlatformObjectFramework\9.4 ImportPackage -subprop "%PROFILE%\%~1.subprop" -newOnly -includeACL -profile "%PROFILE%" -package "%PROFILE%\%~1.spk" -log "%PROFILE%\import_%~1.log" -target "%SASFOLDER%" %~2 %~3 %~4 %~5 %~6 %~7 %~8 %~9 GOTO END :INVALID GOTO END :END CD %CURRENT% PAUSE

Modify the code and place it in a text file named ImportCIObject.cmd. From the directory that contains this file, execute the command with the following syntax: ImportCIObject package-name

[-options]

The command takes the following arguments: package-name is the name of the package that contains the exported objects. -options are the batch import tool options.

Batch Export and Import Tool Examples The following example exports an object that is named my campaign. Because the name contains spaces, it is enclosed in quotation marks. The public object type is CICampaign. Dependencies are included in the export. ExportCIObject CICampaign "my campaign" -includeDep

The following example imports a package that is named my campaign. Because the name contains spaces, it is enclosed in quotation marks. The .spk package extension is not included in the name. ImportCIObject "my campaign"

Load Treatments

385

Load Treatments Overview of the Load Treatments Utility The Load Treatments utility loads internal SAS Customer Intelligence treatments from external tables. The utility reads treatments and their custom details from SAS data sets. This utility does not update treatments within campaigns. If an error is returned for a particular treatment, that treatment is skipped. The utility continues to load the rest of the treatments. You can run the Load Treatments utility more than once on the same tables. The utility updates existing treatments that have the same name and folder. If there any differences from the previous version of a treatment, the treatment version number is incremented. The treatment name and folder name form the unique ID of a treatment. You cannot use the Load Treatments utility to rename a treatment or to move a treatment to a new folder. Instead, delete the treatment and run the Load Treatments utility to load the treatment with the changed name or folder. If there are multiple entries with the same name or folder in the treatment table, the last entry overwrites the first entry. The version number might be incremented. If columns in the input tables are wider than the associated column in the common data model, the values are truncated in the common data model. Load Treatments utility creates a new version of the treatment with the data found the treatment and custom detail tables that you specify on the command line. Only custom details that are in the custom detail table that you specify are in the new version of the treatment. You can use the Load Treatments utility to remove old custom details from a treatment by not specifying rows corresponding to that treatment in the table that contains those customer details.

How to Use the Load Treatments Utility The Load Treatments utility is contained in the sasciutils.exe file on Windows and in the sasciutils file on UNIX. To write the results to the console rather than to the log, use sasciutils_console.exe or sasciutils_console. On Windows, the sasciutils.exe file is typically installed on the middle tier in C: \Program Files\SASHome\SASCustomerIntelligenceUtilities\6.5. From the Windows directory that contains the sasciutils.exe file, execute the command with the following syntax: sasciutils -loadtreatments -argument1 -argument2 On UNIX, the sasciutils file is typically installed on the middle tier in ./SASHome/ SASCustomerIntelligenceUtilities/6.5. From the UNIX directory that contains the sasciutils file, execute the command with the following syntax: sasciutils -loadtreatments -argument1 -argument2 The command takes the following arguments:

386 Appendix 4 / Command-Line Utilities -loadtreatments specifies the Load Treatments utility -domain specifies the domain of the ID. This argument is optional. -id is the ID of the that is used to execute the utility. - is the for the ID. -bcname is the name of the business context. -libname is the library name of the tables that contain the treatments (for example, "Treatment Tables"). -treatmenttablename is the name of the treatment table. The treatment table, custom detail table, and treatments to delete table must be in the same library. -rulestablename is the name of the table that stores inbound rules. The information includes rule types and time periods. Inbound rules are specified when you create a treatment. For more information, see SAS RealTime Decision Manager: ’s Guide. -customdetailtablename is the name of the custom detail table. The treatment table, custom detail table, and treatments to delete table must be in the same library. -treatmentstodeletetablename deletes the specified treatment table. The treatment table, custom detail table, and treatments to delete table must be in the same library.

Treatment Tables Treatment tables should contain the following fields. Table A4.2

Treatment Table Fields

Field

Description

Maximum Character Length*

Example

NAME

The name of the treatment. It cannot contain any forward slashes (/), backslashes (\), or control characters.

60

Little Red Corvette

Load Treatments FOLDER

The location relative to the business context root data folder. The specified folder must already exist. Otherwise, an error is returned for that treatment.

387

This field is not stored in the common data model.

Treatments\September

Note: This is a folder in SAS Management Console. DESCRIPTION

The treatment description

256

Toy car

CODE

The treatment code

32

LRC001

ASSET_LINK_LABEL

The display value of the treatment reference

500

Little Red Corvette

ASSET_LINK_URL

The URL of the treatment reference

500

www.sas.com/lrc.img

START_DATE

The activation date in the treatment properties

8

END_DATE

The expiration date in the treatment properties

8

HIDDEN

Specifies whether a treatment is hidden. 0 specifies that the treatment is not hidden. Any number other than 0 specifies that the treatment is hidden. If this field is not present, the treatment is not hidden.


1

* For the treatment fields that are published to the common data model, the maximum character length is determined by the sizes used

when the common data model treatment-related tables were created.

Treatment Rules Tables Treatment rules tables should contain the following fields. Table A4.3

Treatment Rules Table Fields

Field

Description

Maximum Character Length

TREATMENT_NAME

The name of the treatment. It cannot contain any forward slashes (/), backslashes (\), or control characters.

60 Note: This field must match the NAME field in the TREATMENTS table, which has a limit of 60

388 Appendix 4 / Command-Line Utilities TREATMENT_FOLDER

The location of the treatment relative to the business context root data folder. The specified folder must already exist. Otherwise, an error is returned for that treatment.


RULE_NAME

The name of the inbound rule.

60

RULE_TYPE

The localized value of the rule type: s,Presentations, or Responses.

This field must match one of the locale-specific rule types.

INTERVAL_UNIT

The localized value of the time interval for the rule: Hours, Days, Weeks, or Months.

This field must match one of the locale-specific interval units.

INTERVAL_PERIOD

The number of interval units (for example, 2 weeks).

8

FREQUENCY

The number in the Count field for the rule (for example, 1 response).

8

Note: This field must match the FOLDER field in the TREATMENTS table.

Treatment Custom Detail Tables Treatment custom detail tables should contain the following fields. For a particular treatment, the order of custom details in the table is the order of custom details in the loaded treatment. Multiple custom details with the same name, whether they have the same type, cannot be in the same treatment. Table A4.4

Treatment Custom Detail Table Fields

Field

Description

Maximum Character Length

Example

TREATMENT_NAME

The name of the treatment. The name must be 60 characters or fewer in length. It cannot contain any forward slashes (/), backslashes (\), or control characters.

60

Little Red Corvette

Load Treatments TREATMENT_FOLDE R



Treatments \September

CUSTOM_DETAIL_N AME

The name of the treatment custom detail. The custom detail name must be unique within a treatment.

60

Size

TYPE

The default values are defined in UtilResources.pro perties. See below for more information.


Text

STRING_VALUE

This value is used as a default or initial value if the type is Text or List. If type is List, and multiple values are allowed, then this value is a list of strings that is separated by the list delimiter character that is specified in SAS Customer Intelligence. If the type is List, the value in the STRING_VALUE column must be in the specified list table. Otherwise, an error is returned.

500

1/4 in.

DOUBLE_VALUE

The value is used as a default or initial value if the type is Numeric or Check box. If type is Check box, then zero is false and nonzero is true. An error is returned if the DOUBLE_VALUE column is not numeric.

Not applicable.

0.5

389

390 Appendix 4 / Command-Line Utilities DATE_VALUE

This value is used as the default or initial date value if the type is Date. An error is returned if the DATE_VALUE column is not numeric.

8

15639

LINK_LABEL

This value is used as the default or initial display value if the type is

500

Small Car

LINK_URL

This value is used as the default or initial URL value if type is Link.

500

www.sas.com/ smallcar.img

REQUIRED_FLAG

Specifies whether a value is value required for this custom detail. Y specifies that the value is required. Otherwise, the value is not required.


Y

Link.

If the custom detail is static, the REQUIRED_FLA G is set to Y.

Note: The value for the link is a concatenation of the link label and the link URL.

Load Treatments COLUMN_NAME

The column name used for this custom detail in the UDF extension tables in the common data model. The values in the COLUMN_NAME field of the custom detail have the same restrictions as when the treatment is created in SAS Customer Intelligence. The length of a name must be between 1 and 60 characters. Names cannot include leading or trailing blank spaces, forward slash (/) characters, backslash (\) characters, or any control characters.

30

CAR_SIZE

TAG_NAME

Specifies whether a custom detail tag name is associated with this custom detail. Y specifies that a tag name is associated. Otherwise, a tag name is not associated.

60

CarSize

STATIC_FLAG

Specifies whether a custom detail is static or dynamic. If the custom detail is dynamic, the value of the custom detail can be overridden. Y specifies that the custom detail is static. Otherwise, the custom detail is dynamic.


N

An error is returned if a UDF is static and has no default value. If the custom detail is static, the REQUIRED_FLA G is set to Y.

391

392 Appendix 4 / Command-Line Utilities ALLOW_MULTIPLE_ LIST_VALUES_FLG

If the type is

List, this flag

determines whether multiple items can be selected as the value of this custom detail. Y specifies that multiple items can be selected. Otherwise, multiple items cannot be selected.

DYNAMIC_LIST_FLA G

If the type is

List, this flag

determines whether the available values for the list are read from a table each time that the value is selected or read only once.

LIST_LIB_NAME, LIST_TABLE_NAME, LIST_VALUE_COLU MN, LIST_DISPLAY_VALU E_COLUMN

These fields are used if the type is List. This field specifies where to read the values for the list. The values in the LIST_VALUE_CO LUMN must be unique. This field can be empty.



These fields are not stored in the common data model.

The values for the Type field in the Treatment Custom Detail table are defined in CIUtilities/Source/Java/com/sas/analytics/crm/util/client/ UtilResources.properties. The default values are as follows. Utilities.LoadTreatments.numericType.txt = Numeric Utilities.LoadTreatments.dateType.txt = Date Utilities.LoadTreatments.textType.txt = Text Utilities.LoadTreatments.checkboxType.txt = Check box Utilities.LoadTreatments.listType.txt = List Utilities.LoadTreatments.linkType.txt = Link

Type values are case-sensitive.

Treatments to Delete Table The Treatments to Delete table should contain the following fields. Field

Description

Write Response Definition Data to XML

393

NAME

The name of the treatment. The name must be 60 characters or fewer in length. It cannot contain any forward slashes (/), backslashes (\), or control characters.

FOLDER


List Values Tables In the list values tables, the name of the list value column must match the value of LIST_VALUE_COLUMN in the custom detail table. The name of the display value column must match the value of LIST_DISPLAY_VALUE_COLUMN in the custom detail table.

Load Treatment Utility Example The following example loads the treatments from a CI_TREATMENT_IMPORT table that is in a library named TREATMENTLIBNAME. The CI_TREATMENT_CUST_DTLS table is also loaded. The results are printed to load_treatments.out. sasciutils -loadtreatments -domain mydomain -id myid - my -bcname mybusinesscontext -libname "Treatment Tables" -treatmenttablename CI_TREATMENT_IMPORT -customdetailtablename CI_TREATMENT_CUST_DTLS > load_treatments.out

Write Response Definition Data to XML Overview of the Response Definition Data Utility The Response Definition Data utility writes response definition surrogate key (SK) and code data to XML so that response definitions can be migrated to the next release. You execute this utility after migration if writing the response definition data was omitted from the migration process.

How to Use the Response Definition Data Utility The Response Definition Data utility is contained in the sasciutils.exe file on Windows and in the sasciutils file on UNIX. To write the results to the console rather than to the log, use sasciutils_console.exe or sasciutils_console. On Windows, the sasciutils.exe file is typically installed on the middle tier in C: \Program Files\SASHome\SASCustomerIntelligenceUtilities\6.5. From the Windows directory that contains the sasciutils.exe file, execute the command with the following syntax: sasciutils -action DumpResponseSK argument1 -argument2

394 Appendix 4 / Command-Line Utilities On UNIX, the sasciutils file is typically installed on the middle tier in ./SASHome/ SASCustomerIntelligenceUtilities/6.5. From the UNIX directory that contains the sasciutils file, execute the command with the following syntax: sasciutils -action DumpResponseSK -argument1 -argument2 The command takes the following arguments: -action DumpResponseSK specifies the Response Definition Data utility. -id is the ID of the that is used to execute the utility. - is the for the ID. -metaserver specifies the Domain Name System (DNS) name of the metadata server. -metaport specifies the port for the metadata server. -metadomain specifies the domain for authentication (for example, DefaultAuth). This argument is optional. -responseskfile specifies the response SK map path and output XML filename. -logfile specifies the log path and output log filename. -threads specified the number of simultaneous objects that are affected. The default is 1. -debug enables debugging text. This argument is optional.

Response Definition Data Utility Example The following example writes the output to /install/temp/ myresponsedump.xml. Four threads are affected. The metadata server is myserver.na.sas.com. The port is 8561. The domain is DefaultAuth. A log file is written to /install/temp/responsedump.log. Debugging text is turned on. sasciutils -action DumpResponseSK -id my - myid -metaserver myserver.na.sas.com -metaport 8561 -metadomain DefaultAuth -responseskfile /install/temp/myresponsedump.xml -logfile /install/temp/responsedump.log -threads 4 -debug

Lineage Overview of the Lineage Utility The Lineage utility provides information about the lineage relationships between SAS Real-Time Decision Manager objects.

Lineage

395

The Lineage utility requires the Log on to Customer Intelligence applications capability. For more information, see “Predefined Roles for SAS Customer Intelligence” on page 95.

How to Use the Lineage Utility The Lineage utility is contained in the sasciutils.exe file. The typical location of this file is on the middle tier inC:\Program Files\SASHome \SASCustomerIntelligenceUtilities\6.5. From the directory that contains the sasciutils.exe file, execute the command with the following syntax: sasciutils -lineage argument1 -argument2 The command takes the following arguments: -lineage specifies the domain object type and optional subtype for the Lineage utility. For more information, see “Lineage Utility Domain Object Types” on page 397. -id is the ID of the that is used to execute the utility. - is the for the ID. -bcname specifies the name of the single business context to be processed.

Lineage Utility Output The output text is sent to the console output using the following values. : / : / Each line corresponds to one lineage between two objects, and is terminated by a linefeed. Here is an example of the console output: sukstcSL1:id CFFH4M1UF3BHRWKE/CIDecisionProcess "A" FROM using self learner 1 id:HGEDMFAH2NDFTHVS/CICampaign_Decision

Lineage Utility Relationships The following table lists and describes the output abbreviations for the relationships in the Lineage utility. Table A4.5

Output Abbreviations

Output abbreviation

Name

Description

"A"

Associated

The object on the left is loosely associated with the object on the right.

396 Appendix 4 / Command-Line Utilities Output abbreviation

Name

Description

"D"

Depends

The object on the left is dependent on the right for it to function properly.

"I"

Includes

The object on the left includes the object on the right.

The following table lists and describes the directions for the relationships in the Lineage utility. Table A4.6

Directions

Direction

Description

"TO"

The object on the left is the owner or parent in the relationship with the right hand object.

"FROM"

The object on the left is managed or owned by the right hand object.

The following table lists the relationship types and directions for left objects and right objects in the Lineage utility. Table A4.7

Relationship Types and Directions for Left and Right Objects

Left Object

Relationship Type

Direction

Right Object

CITreatmentCampa ignSet

Includes

TO

CICampaign_Decis ionTreatment


Depends

TO

RTDMFlow


Associated

FROM

CICampaign_Decis ion


Includes

FROM



Depends

TO

RTDMFlow


Associated

TO

CIDecisionProcess


Depends

TO

RTDMFlow


Associated

TO

CIDecisionProcess

Lineage

397

Left Object

Relationship Type

Direction

Right Object


Associated

TO


CIDecisionProcess

Associated

FROM


CIDecisionProcess

Associated

FROM


CIDecisionProcess

Depends

TO

Model

CIDecisionProcess

Depends

TO

Decision

CIDecisionProcess

Depends

TO

RuleFlow

RTDMFlow

Depends

FROM


RTDMFlow

Depends

FROM


RTDMFlow

Depends

FROM


Model

Depends

FROM

CIDecisionProcess

Decision

Depends

FROM

CIDecisionProcess

RuleFlow

Depends

FROM

CIDecisionProcess

Lineage Utility Domain Object Types The following table lists and describes the domain object types for the Lineage utility. Domain Object Type

Description

CICampaign_Decision

Decision campaign

CICampaign_DecisionTreatment

Decision treatment campaign

CIDecisionProcess

Decision process definition

CITreatmentCampaignSet

Treatment campaign set

Decision

Decision Builder flow

Model

SAS Model Manager model

RTDMFlow

SAS Decision Services flow

398 Appendix 4 / Command-Line Utilities Domain Object Type

Description

RuleFlow

SAS Business Rules Manager rule

If the object is a CIDecisionProcess, the definition can include one of the following sub-types: n .models n .rules n .selflearner n .sas n .read n .update n .insert n .sdm n .web n .celebrus n .java n .dscode n .javacode

Note: If CIDecisionProcess is the only the object type, and does not include any sub-types, then all the process types in the lineage list will be used.

Lineage Utility Examples The following example lists the relationship links between a rule process definition and other objects: sasciutils -lineage CIDecisionProcess.rules -id Myid - My -bcname NorthWestBanking

The following example lists the relationship links for a decision treatment campaign: sasciutils -lineage CICampaign_DecisionTreatment -id Myid -bcName NorthWestBanking - My

The following example lists the relationship links for a decision campaign: sasciutils -lineage CICampaign_Decision -id Myid -bcName NorthWestBanking - My

For a campaign with a score node, a rules node, several treatments, a treatment campaign set, and marked for deployment, the example output is created: myCampaign:id A5OOUZVB.AF0000PO/TransformationActivity "A" TO myRuleDefinition id:A5OOUZVB.AA0002HH/Group myCampaign:id A5OOUZVB.AF0000PO/TransformationActivity "A" TO mySet id:A5OOUZVB.AA0002I8/Group myCampaign:id A5OOUZVB.AF0000PO/TransformationActivity "A" TO myTreatment1 id:A5OOUZVB.AA0002IA/Group myCampaign:id A5OOUZVB.AF0000PO/TransformationActivity "A" TO myTreatment2 id:A5OOUZVB.AA0002IB/Group

Clean Up Production Repository

399

myCampaign:id A5OOUZVB.AF0000PO/TransformationActivity "A" TO myTreatment3 id:A5OOUZVB.AA0002IC/Group myCampaign:id A5OOUZVB.AF0000PO/TransformationActivity "A" TO myModelDefinition id:A5OOUZVB.AA0002I9/Group myCampaign:id A5OOUZVB.AF0000PO/TransformationActivity "D" TO myCampaign:G_Assets\G_Business_Contexts\ NorthWestBanking\Myid\Lineage:G_BC_ORASmall id:myCampaign_1_FHBAGBM0AZGMQCJZ/RTDMFlow

The following example lists the relationship links for a self-learner definition: sasciutils -lineage CIDecisionProcess.selflearner -id Myid -bcName NorthWestBanking - My

The following example lists the relationship links for a treatment campaign set. sasciutils -lineage CITreatmentCampaignSet -id Myid -bcName NorthWestBanking - My

The following example output is created if a campaign set named mySet includes two member campaigns, is dependent on the RTDMFlow to function, and is used in a parent campaign: mySet:id A5OOUZVB.AA0002I8/Group "I" TO (DBHBWW3KHNBWQEGE) id:A5OOUZVB.AF0000PL/TransformationActivity mySet:id A5OOUZVB.AA0002I8/Group "I" TO (FFGGI5LAZZFHQYVP) id:A5OOUZVB.AF0000PM/TransformationActivity mySet:id A5OOUZVB.AA0002I8/Group "D" TO mySet:G_Assets\G_Business_Contexts\NorthWestBanking\Myid \Lineage:G_BC_ORASmall id:mySet_TS_BCAFED00QVDPR0IU/RTDMFlow mySet:id A5OOUZVB.AA0002I8/Group "A" FROM myCampaign id:A5OOUZVB.AF0000PO/TransformationActivity

The following example displays the lineage between treatments and campaigns: sasciutils -lineage CITreatment -id Myid -bcName NorthWestBanking - My

This command produces the following example output: myTreatment1:id A5OOUZVB.AA0002IA/Group "A" FROM myCampaign id:A5OOUZVB.AF0000PO/TransformationActivity myTreatment2:id A5OOUZVB.AA0002IB/Group "A" FROM myCampaign id:A5OOUZVB.AF0000PO/TransformationActivity

Clean Up Production Repository Overview of the Clean Up Engine Repository Utility The Clean Up Engine Repository utility enables you to remove orphaned decision treatment campaigns and other unused objects from the production repository. You must have Write access to the repository in order to remove objects. For information ing SAS Customer Intelligence Studio to remove unused objects, see “Remove Unused Objects from the Production Repository” on page 246.


How to Use the Clean Up Engine Repository Utility The Clean Up Engine Repository utility is contained in the sasciutils.exe file on Windows and in the sasciutils file on UNIX. To write the results to the console rather than to the log, use sasciutils_console.exe or sasciutils_console. On Windows, the sasciutils.exe file is typically installed on the middle tier in C: \Program Files\SASHome\SASCustomerIntelligenceUtilities\6.5. From the directory that contains the sasciutils.exe file, execute the command with the following syntax: sasciutils.exe -cleanupenginerepository -argument1 -argument2 On UNIX, the sasciutils file is typically installed on the middle tier in ./SASHome/ SASCustomerIntelligenceUtilities/6.5. From the UNIX directory that contains the sasciutils file, execute the command with the following syntax: sasciutils -cleanupenginerepository -argument1 -argument2 The command takes the following arguments. -id

ID of an with Write access -

-domain

Domain name -bcname

Business context name —cleanupinactiveflows

Removes inactive flows —cleanupunusedactivities

Removes unused activities —cleanupunusedevents

Removes unused events —cleanupunusedtcs

Removes unused treatment campaign sets —cleanupunuseddtc

Removes unused decision treatment campaigns —cleanuptest

Identifies unused objects but does not remove them from the repository. A list of the unused objects is written to SASCustIntelCore6.5.log. —remotesystemname

The name of the remote system. Omit the remote system options if you are removing objects from a local repository. —remotesystemprotocol

The access protocol (for example, HTTP) for the remote system -remotesystemport

The port number for the remote system

Use the Launcher to Complete Tasks

401

-authdomain

The authentication domain for the remote system

Use the Launcher to Complete Tasks Overview of the Launcher The Launcher application is a command-line utility that you use to perform the following tasks: n Run test cases n Mark campaigns for deployment n Generate reports that list input variables n Publish campaigns and treatment campaign sets to a reporting library n Manage remote deployments of campaigns and activities n Run the self-learner training

The executable for the Launcher application is sasmalauncher.exe. On Windows, this file is typically located in C:\Program Files\SASHome \SASMarketingAutomationLauncher\6.5. On UNIX, it is typically located in SASHome/SASMarketingAutomationLauncher/6.5 .

Launcher Command Syntax The Launcher command uses the following syntax: sasmalauncher.exe -d directive -u id -p -x business context[-n -q -v] [--] directive arguments

Use the -d option to specify one of the following directives: -d activate | camp | deactivate | deploy | input variables | maintenance | mark | publish | publish set | test | tests | update_self_learner | undeploy

Note: If the drgm directive was used in a Launcher command in a previous release, it is converted to the camp directive in Release 6.5. The command also takes any of the following options: -u ID

specifies the ID of the who is responsible for executing this command. -U

specifies the ID of the remote system . -p

specifies the for the ID. -P

specifies the for the ID for the remote system. –g assigns a ID to identify the campaign.

402 Appendix 4 / Command-Line Utilities -x

specifies the name of business context that corresponds to the campaign. Spaces are allowed; the business context name is not case-sensitive. -E

encrypts the remote system (otherwise, the appears in clear text) -v

specifies informative messages in the log. If not specified, only errors are displayed. -n

specifies that arguments are given by using the path and name rather than by identifier. The path and name must be provided in URI (Universal Resource Indicator) format unless option -q is specified. -q

specifies that arguments are either quoted or have no spaces. URI translation of arguments is suppressed when this option is specified. --

specifies the end of the options. All parameters after this are directive arguments. directive arguments is a list of arguments, separated by spaces. See Table A4.9 on page 404 and Table A4.8 on page 403 for the directives that are associated with each argument. These are the possible arguments: assetType type of asset to mark for deployment. The value is camp. business context ID uses the settings of the specified business context to regenerate metadata. Any saved settings are overridden by the directive arguments. campID campaign ID camp path folder path and campaign name clearCache information map cache to be cleared after map is generated genType describes the method used. 1 is SQL. 2 is PROC SUMMARY. maintenance options options for maintenance. The values are f to remove inactive flows, e to remove unused events, a to remove unused activities, s to remove unused treatment campaign sets, or t to remove unused decision treatment campaigns. You can enter the options in any order. By default, the options are executed in the following order: f, e, s, t, a. remote name name of the remote system report name folder and filename of input variables report


403

setId test case ID set path folder path and campaign set name testId test case ID testName name of the test case in the campaign testResultFile test result log file path testSaveMode indicates whether a campaign is to be saved again after the test runs. The values are save or nosave (default). testType indicates whether a campaign is to be tested. The value is camp. typeArgs space-delineated list of table-type arguments The campID argument is an identifier that is assigned by the SAS Real-Time Decision manager application server. It is not intended to be entered by the on the command line, but it can be used if the -n option is not used. In the following table, the -n option has not been specified. Table A4.8

Arguments When the -n Option Has Not Been Specified

Directive

Arguments

Description

activate

assetType campId or setIdremoteName

activates a flow on a remote system. Directives -U, -P, or -E might also be required.

deactivate


deactivates a flow on a remote system. Directives -U, -P, or -E might also be required.

deploy


deploys a flow on a remote system. Directives -U, -P, or -E might also be required.

test

testType campId testId [testSaveMode] [testResultFile]

runs a test case, saves the flow, and logs the test results

tests

testType campID [testSaveMode] [testResultFile]

runs all test cases, saves the campaign, and logs the test results

undeploy

assetType campId or setId remoteName

undeploys a flow on a remote system

404 Appendix 4 / Command-Line Utilities You can enter the path argument on the command line if the -n option has been specified. If an application server that is not the standard is used, the application server also uses this argument with the -n option. The following table lists the arguments to use when the -n option has been specified. All objects are identified by name or by folder and name. Table A4.9

Arguments When the -n Option Has Been Specified

Directive

Arguments

Description

activate

assetType camp path or set pathremoteName

activates a flow on a remote system

deactivate

assetType camp path or set pathremoteName

deactivates a flow on a remote system

deploy

assetType campId remoteName

deploys a flow on a remote system

inputvariables

report name

generates a list of input variables in PDF format

maintenance

remote name maintenance options

runs maintenance on a remote system

mark

assetType file path

marks an asset for deployment

publish

assetTypecampname reporting library

publishes a campaign to the specified reporting library

publish set

assetTypetreatmentsetnam e reporting library

publishes a treatment campaign set to the specified reporting library. All of the treatment campaign set must be marked for deployment.

test

testType campname test name [testSaveMode] [testResultFile]

runs a test case, saves the campaign, and logs the test results

tests

testType path [testSaveMode] [testResultFile]

runs all test cases, saves the campaign, and logs the test results

update_self_learner

assetType camp name or set name file path (for the self-learner definition)

runs the self-learner training

undeploy

assetType camp name or set name remoteName

undeploys a flow on a remote system


405

Example of Listing Input Variables You can generate a single list of input variables for all of the campaigns in a business context. You can quickly review the list to determine whether a specific variable is used. The list contains the node name or treatment where the variable is used, and the type of usage, whether variable, identifier, or calculated item. The following command writes input variables to a file named report.pdf. sasmalauncher.exe -u myid -p my -x mybusinesscontext -n -q -v -d inputvariables c:/public/report.pdf

In order to generate a complete report, you should have access to all of the campaigns and events. Otherwise, the generated report is incomplete.

Example of Publishing to a Reporting Library You can perform a full publish of a campaign to a specified reporting library. The destination library might be different from the reporting library for the source business context. All of a treatment campaign set must be marked for deployment. Only campaigns that have been marked for deployment can be published to a different reporting library. For more information about publishing to a reporting library, see “Saving, Publishing, and the Common Data Model” on page 373 The following command publishes a campaign named Marketing Campaign to a reporting library named CIMARKETING. sasmalauncher -u myid -p my -x "Northwest Business Context" -n -q -v -d publish camp "Customer Intelligence\Campaigns\Marketing Campaign" "CIMARKETING"

The following command publishes a treatment campaign set named Marketing Treatment Set to a reporting library named CIMARKETING. sasmalauncher -u myid -p my -x "Northwest Business Context" -n -q -v -d publish set "Customer Intelligence\Campaigns\Marketing Treatment Set" "CIMARKETING"

If you do not specify a reporting library, the campaign is published to the default library for the business context. For information about reporting libraries, see “Creating Reporting Catalogs” on page 138.. Note: If you cross-publish a campaign to another common data model, you must also publish the decision treatment campaigns and treatment campaign sets that are related to the campaign.

Example of Managing Deployment of Campaigns to Remote Environments You can deploy, undeploy, activate, and deactivate campaigns and campaign sets in a remote environment. You can use maintenance options to remove unused activities, events, inactive flows, decision treatment campaigns, and treatment sets from a remote environment. The following command deploys a campaign to a remote environment using an encrypted : sasmalauncher -u myid -p my -x "Northwest Business Context" -U myid -P

406 Appendix 4 / Command-Line Utilities myencrypted -E -n -q -v -d deploy camp "\Campaigns\Simple Campaign" "RemoteEnvName"

The following command deploys a treatment campaign set to a remote environment using an ID: sasmalauncher -u myid -p my -x "Northwest Business Context" -U myid -P myencrypted -E -q -v -d deploy set "XYZ1234567890" "RemoteEnvName"

The following command undeploys a campaign from a remote environment using an encrypted : sasmalauncher -u myid -p my -x "Northwest Business Context" -U myid -P myencrypted -E -n -q -v -d undeploy camp "\Campaigns\Simple Campaign" "RemoteEnvName"

The following command activates a campaign on a remote environment using an encrypted : sasmalauncher -u myid -p my -x "Northwest Business Context" -U myid -P myencrypted -E -n -q -v -d activate camp "\Campaigns\Simple Campaign" "RemoteEnvName"

The following command deactivates a campaign on a remote environment using an encrypted : sasmalauncher -u myid -p my -x "Northwest Business Context" -U myid -P myencrypted -E -n -q -v -d deactivate camp "\Campaigns\Simple Campaign" "RemoteEnvName"

The following command performs maintenance (cleanup repository) on only activities and events on a remote environment using an encrypted : sasmalauncher -u myid -p my -x "Northwest Business Context" -U myid -P myencrypted -E -n -q -v -d maintenance "RemoteEnvName" "ae"

Example of Deploying an Activity to a Remote Environment You can deploy activities in a remote environment. You can use maintenance options to remove unused activities, events, inactive flows, decision treatment campaigns, and treatment sets from a remote environment. The following command deploys an activity to a remote environment using a name: sasmalauncher -u myid -p my -n -x "Northwest Business Context" -U myid -P myencrypted -E -q -v -d deploy activity "model_XYZ1234567890" "RemoteEnvName"

Example of Running the Self-Learner Training Stored Process You can run the self-learner training stored process. The following command runs the self-learner training process: sasmalauncher -u myid -p my -x "Northwest Business Context" -n -q -v -d update_self_learner "\Definitions\SelfLearnerDefinition"


407

Enable Logging for the Launcher Overview of Logging By default, the launcher logs are stored in the home directory of the who issues the launcher command. The Launcher s two types of logging: General logging logs each execution of the Launcher. Logging information can be written to a different file for each execution or it can be appended to an existing file. Command logging logs a particular execution of the Launcher. Command logging enables you to create logs for specific campaigns. The following considerations apply to command logging: n Command logging runs in Append mode by default. n Command logging can be used only if general logging is enabled. n Command log files are written to the same directory as general log files. If

a directory other than the default has been specified for general logging, then command logs are also written to the specified directory. n Command log filenames are created based on the type of operation, the

object name or ID, and the last directory name in the path. The sasmalauncher.ini file is the Launcher initialization file that contains start-up and configuration parameters for the Launcher. To configure the Launcher’s logging parameters, including log filenames and directories: 1 Locate the sasmalauncher.ini file. 2 Open sasmalauncher.ini. You see Java code similar to the sample file

excerpt that is displayed. 3

Add command lines that specify the logging parameters that you want to change. Add each new command argument at the end of the file.

Locate sasmalauncher.ini sasmalauncher.ini is located by default in the SAS Customer Intelligence installation directory: n UNIX: .../SASMarketingAutomationLauncher/6.5 n Windows: :\Program Files\SASHome

\SASMarketingAutomationLauncher\6.5

Sample Sasmalauncher.ini File Here is an excerpt from the sasmalauncher.ini file: --[properties] MASTERPROP="C:\SASServer\SASHome\sassw.config" [default] startdir=

408 Appendix 4 / Command-Line Utilities applogloc= launchercmd=<JREHOME> mode=console JavaArgs_1=-Denv.definition.location="<SASENVIRONMENTSURL>" JavaArgs_2=-Dma.launcher.logdir="ApplicationData\SAS\SASMarketingAutomationLauncher" JavaArgs_3=-Djava.system.class.loader=com.sas.app.AppClassLoader JavaArgs_4=-Dsas.ext.config="<SASHOME>\sas.java.ext.config" JavaArgs_5=-Dsas.app.launch.config=picklist JavaArgs_6=-Dsas.app.repository.path=" \eclipse" JavaArgs_7=-Dsas.app.class.path=.;"C:\SASServer\SASHome\SASMarketingAutomationLauncher\ 6.5\build" JavaArgs_8=-Dsas.app.launch.picklist=picklist;"help\primary.picklist" JavaArgs_9= Classpath=- " /eclipse/plugins/sas.launcher.jar" MainClass=com.sas.analytics.crm.ma.launcher.MALauncher

Add Command-Line Arguments (sasmalauncher.ini) Use these Java Runtime Environment (JRE) commands within sasmalauncher.ini to perform the corresponding task. No spaces are allowed in the Java argument unless the path string is enclosed in quotation marks. To direct general logging information to a log file without specifying a filename: -Dma.launcher.log (for example, JavaArgs_7=-Dma.launcher.log) A separate log file is created in the <SASHome> \SASMarketingAutomationLauncher\6.5 directory for each Launcher call that is made. The filename is assigned as the time expressed in milliseconds (for example, 1268841617289.log). In addition to the sassrv who must have WRITE permission, the who might manually start the Launcher must also have WRITE permission to the directory. To create a general log file with a specified filename: -Dma.launcher.log= (for example, JavaArgs_2=Dma.launcher.log=february.log) If the file does not exist, then it is created. You must manually specify the .log extension in the filename if you want the extension to be used. To append the general log output to an existing file: -Dma.launcher.log=filename (for example,JavaArgs_2=Dma.launcher.log=january.log) You must manually specify the .log extension in the filename when you create the file if you want the file extension to be used in the filename. To direct all logging information to a directory within the home directory of the Launcher application: -Dma.launcher.logdir=" " (for example, JavaArgs_2=Dma.launcher.logdir="logs") The directory must exist. Enclose a path in double quotation marks. To direct all logging information to an absolute directory: -Dma.launcher.abslogdir=" " (for example, JavaArgs_2=-Dma.launcher.abslogdir="\\srshq\root\logs \launcher")


409

Another example is: JavaArgs_2=-Dma.launcher.abslogdir="C: \deptZed\logs\launcher" The directory must exist. In addition to the sassrv who must have Write permission, the who might manually start the Launcher must also have Write permission to the directory. To enable command logging in Append mode: -Dma.launcher.commandlogmode= (for example, JavaArgs_9=Dma.launcher.commandlogmode=append) To enable command logging in Replace mode: -Dma.launcher.commandlogmode=replace (for example, JavaArgs_9=Dma.launcher.commandlogmode=replace)

To enable the decoding of U+ Unicode strings JavaArgs_xx=-Dma.unicode.marker=U+ xx is the next number in the list of Java arguments.

Troubleshooting the Most Common Launcher Errors These are the three most common error codes that might be generated by the Launcher: n Unexpected Error n Execution Failed n Unable to Log onto Application Server

Unexpected Error, Execution Failed First, check for errors in the logs of the SAS Real-Time Decision Manager engine on the application server at<SASPlanName>/Lev1/Web/Logs/ SASServer6_1. Next, start the Launcher from a command prompt on the computer where the Launcher is installed, and determine whether the same error or a different error occurs. Unable to Log onto Application Server When the Launcher cannot log on to SASServer6, that SASServer6 is running.

List of Error Codes These are the error codes that can be returned by the Launcher. If a remedy or strategy for handling an error is available, then it is included in the error description. 01 Unexpected error 10 Invalid command line Compare the generated Launcher command with the valid Launcher command-line arguments. 11 Invalid directive The value for the directive in the -d option is not allowed.

410 Appendix 4 / Command-Line Utilities 12 Invalid argument scheme The list of arguments either does not correspond to the directive or is not valid for the directive that is specified by the -d option. 13 Ambiguous argument scheme The list of arguments is ambiguous for the selected directive that is specified with the -d option. This error occurs when a conflict exists because either the -n option is used to name arguments that are not provided in the correct format, or the named arguments do not correspond to the selected directive. 20 Unable to log on to application server See “Unable to Log onto Application Server” on page 409. 21 Unable to acquire execution service The Launcher cannot connect to the execution service within the application server. The Launcher uses an EJB (Enterprise JavaBeans) execution within the application server. 23 Unable to switch to context 24 Unable to acquire Security Manager 30 Execution failed The Launcher command failed to execute. In UNIX operating environments, this error indicates that the does not have permission to create and update information map metadata tables. 32 Object to execute is locked by another The object to be executed is already opened by another client. The Locks category in the istration workspace of SAS Customer Intelligence enables you to view and release objects that are locked, such as campaigns. 34 Identifier resolve failure It was not possible to resolve the specified identifier. Either the identifier no longer exists, or the specified identifier is incorrect. In extreme circumstances, this error is displayed if the specified campaign name has been incorrectly resolved from corrupted metadata. 40 Campaign failed to generate correctly in running test case 41 Test case failed 42 Test case not found 46 Campaign is locked In some circumstances, you might not be able to edit an object such as a campaign or treatment, even if you have Edit permission. To unlock an object so that you can edit it, select the Locks category in the istration workspace in SAS Customer Intelligence. the holder of the lock before you release the object. 50 Campaign name not found The specified campaign name and path could not be found. Either the campaign no longer exists, the specified name is incorrect, or the path is incorrect. 60 File does not exist The specified file does not exist. 61 File cannot be deleted The specified file cannot be deleted. 62 File cannot be written The specified file cannot be written.


411

70 Campaign cannot be marked for deployment The campaign cannot be marked for deployment because it has not been approved. 71 of the treatment campaign set are not marked for deployment The treatment campaign set has been marked for deployment but some or all of the of the treatment campaign set are not marked for deployment. 72 Treatment campaign set could not be opened with Write access 73 You need View permissions You need View permissions on all to mark the set ready for deployment. 90 Problem while logging off the application server This error occurs after the object is successfully executed by the application server, but before the Launcher is disconnected. Look for error messages in the log file of SASServer6. 91 Problem releasing execution service The Launcher cannot release the execution service within the application server. The Launcher uses an execution EJB (Enterprise JavaBeans) within SASServer6. 100 Campaign cannot be published as it has not been marked for deployment 110 Remote environment is not in the list of managed remote deployments 111 Campaign or treatment campaign set is not in the list of actionable objects 112 Problem performing remote action on the specified object


413

Appendix 5 %CI2LASR Output Table Data Dictionary The %CI2LASR macro extracts common data model data to an output table. The data is used for reports. For more information, see “Extract Data” on page 207. The following table does not include columns that are built from the customized extension (_EXT) tables. Those columns depend on the common data model implementation at your site.

Type NUM

NUM

CHAR NUM NUM

CHAR

CHAR CHAR

NUM NUM NUM CHAR

NUM CHAR

Column Name

CAMPAIGN_MAX_OFFER

COMMUNICATION_MAX_OFFER

CAMPAIGN_CD

RUN_DTTM

CAMPAIGN_VERSION_NO

CAMPAIGN_CURRENT_VER_FLG

CAMPAIGN_NM

CAMPAIGN_FOLDER_TXT

CAMPAIGN_START_DTTM

CAMPAIGN_END_DTTM

LAST_MODIFIED_DTTM

LAST_MODIFIED_BY__NM

APPROVAL_DTTM

APPROVAL_GIVEN_BY_NM

Table A5.1 %CI2LASR Macro Output Table Data Dictionary

240

8

240

8

8

8

4096

240

4

8

8

120

8

8

Length

$240

DATETIME20.

$240.

DATETIME20.

DATETIME20.

DATETIME20.

$4096.

$240.

$4.

7.

7.

$120.

16.2

16.2

Format

$240

DATETIME20.

$240.

DATETIME20.

DATETIME20.

DATETIME20.

$4096.

$240.

$4.

7.

7.

$120.

16.2

16.2

Informat

CI_CAMPAIGN,COLUMN: BUSINESS_CONTEXT_NM

CI_CAMPAIGN,COLUMN: APPROVAL_DTTM

CI_CAMPAIGN,COLUMN: LAST_MODIFIED_BY__NM

CI_CAMPAIGN,COLUMN: LAST_MODIFIED_DTTM

CI_CAMPAIGN,COLUMN:END_DTTM

CI_CAMPAIGN,COLUMN: START_DTTM

CI_CAMPAIGN,COLUMN: CAMPAIGN_FOLDER_TXT

CI_CAMPAIGN,COLUMN: CAMPAIGN_NM

CI_CAMPAIGN,COLUMN: CURRENT_VERSION_FLG

CI_CAMPAIGN, COLUMN: CAMPAIGN_VERSION_NO

CI_CAMPAIGN, COLUMN: RUN_DTTM

CI_CAMPAIGN, COLUMN: CAMPAIGN_CD

CI_COMMUNICATION, COLUMN: MAX_BUDGET_OFFER_AMT

CI_CAMPAIGN,COLUMN: MAX_BUDGET_OFFER_AMT

Common Data Model Source

414 Appendix 5 / %CI2LASR Output Table Data Dictionary

CHAR

NUM NUM

CHAR

CHAR

CHAR

CHAR

CHAR

NUM NUM NUM NUM

CHAR NUM

BUSINESS_CONTEXT_NM

CAMPAIGN_MAX_BUDGET_AMT

COMMUNICATION_OCCURRENCE_NO

COMMUNICATION_NM

SUBJECT_TYPE_NM

COMMUNICATION_CD

COMMUNICATION_STATUS_CD

COMMUNICATION_RECURR_TYPE_CD

COMMUNICATION_START_DTTM

COMMUNICATION_END_DTTM

EXPORT_DTTM

COMMUNICATION_MAX_BUDGET_AMT

PACKAGE_CD

TOTAL_MARKETING_ _CNT

8

128

8

8

8

8

12

12

120

240

240

8

8

240

NLNUM16.

$128.

16.2

DATETIME20.

DATETIME20.

DATETIME20.

$12.

$12.

$120.00

$240.

$240.

7.

16.2

$240.

$128.

16.2

DATETIME20.

DATETIME20.

DATETIME20.

$12.

$12.

$120.

$240.

$240.

7.

16.2

$240.

The total number of attempted s for the package, minus any failed s (such as bounced e-mail messages). This value is a count of subjects such as Customer, Household, or .

CI_CELL_PACKAGE,COLUMN: PACKAGE_CD

CI_COMMUNICATION,COLUMN: MAX_BUDGET_AMT

CI_COMMUNICATION,COLUMN: EXPORT_DTTM

CI_COMMUNICATION,COLUMN: END_DTTM

CI_COMMUNICATION,COLUMN: START_DTTM

CI_COMMUNICATION,COLUMN: COMMUNICATION_RECURR_TYPE_CD

CI_COMMUNICATION,COLUMN: COMMUNICATION_STATUS_CD

CI_COMMUNICATION,COLUMN: COMMUNICATION_CD

CI_COMMUNICATION,COLUMN: SUBJECT_TYPE_NM

CI_COMMUNICATION,COLUMN: SUBJECT_TYPE_NM

CI_COMMUNICATION,COLUMN: COMMUNICATION_OCCURRENCE_NO

CI_CAMPAIGN,COLUMN: MAX_BUDGET_AMT

CI_CAMPAIGN,COLUMN: BUSINESS_CONTEXT_NM

Contents of the %CI2LASR Macro Output Table

415

NUM

CHAR CHAR

NUM

NUM

CHAR

CHAR

CHAR

NUM NUM NUM NUM NUM NUM

TOTAL_ATTEMPTED_ _CNT

CHANNEL_CD

CONTROL_GROUP_TYPE_CD

HO_TOTAL_ATTEMPTED__CNT

HO_TOTAL_MARKETING__CNT

HO_MARKETING_CELL_CD

HO_MARKETING_CELL_NM

HO_CONTROL_GROUP_TYPE_DESC

TOTAL_RESPONSE_CNT

TOTAL_RESPONSE_VAL_AMT

TOT_SUCCESS_ ESPONSE_CNT

TOT_SUCCESS_RESPONSE_VAL_AMT

HO_TOTAL_RESPONSE_CNT

HO_TOTAL_RESPONSE_VAL_AMT

8

8

8

8

8

8

1024

240

128

8

8

12

12

8

NLNUM16.

NLNUM16.

NLNUM16.

$1024.

$240.

$128.

NLNUM16.

NLNUM16.

$12.

$12.

NLNUM16.

$1024.

$240.

$128.

NLNUM16.

NLNUM16.

$12.

$12.

Calculated from CI_RESPONSE_HISTORY.






CI_CONTROL_GROUP_TYPE , COLUMN: CONTROL_GROUP_TYPE_DESC

CI_MARKETING_CELL,COLUMN: MARKETING_CELL_NM

CI_MARKETING_CELL,COLUMN: MARKETING_CELL_CD

The total number of attempted s for the holdout package minus any failed s (such as bounced e-mail messages). This value is a count of subjects such as Customer, Household, or .

The total number of attempted s that were sent to the channel for the holdout package. This value is a count of subjects such as Customer, Household, or .

CI_CELL_PACKAGE,COLUMN: CONTROL_GROUP_TYPE_CD

CI_CELL_PACKAGE,COLUMN: CHANNEL_CD

The total number of attempted s that were sent to the channel for the package. This value is a count of subjects such as Customer, Household, or .


NUM NUM CHAR CHAR CHAR

CHAR

CHAR

NUM NUM NUM

CHAR

CHAR

CHAR

CHAR

CHAR

HO_TOT_SUCCESS_RESPONSE_CNT

HO_TOT_SUCCESS_ RESPONSE_VAL_AMT

TREATMENT_CD

TREATMENT_NM

TREATMENT_REFERENCE_TXT

TREATMENT_REFERENCE_URL

TREATMENT_CURRENT_VER_FLG

TREATMENT_START_DTTM

TREATMENT_END_DTTM

TREATMENT_VERSION_NO

CAMPAIGN_GROUP_CD

CAMPAIGN_GROUP_NM

CAMPAIGN_GROUP_FOLDER_TXT

CAMPAIGN_GROUP_TYPE_DESC

CAMPAIGN_STATUS_DESC

1024

1024

4096

240

120

8

8

8

4

2000

2000

240

128

8

8

$1024.

$1024.

$4096.

$240.

$120.

7.

DATETIME20.

DATETIME20.

$4.

$2000.

$2000.

$240.

$128.

NLNUM16.

$1024.

$1024.

$4096.

$240.

$120.

7.

DATETIME20.

DATETIME20.

$4.

$2000.

$2000.

$240.

$128.

CI_CAMPAIGN_STATUS , COLUMN: CAMPAIGN_STATUS_DESC

CI_CAMPAIGN_GROUP_TYPE , COLUMN: CAMPAIGN_GROUP_TYPE_DESC

CI_CAMPAIGN_GROUP,COLUMN: CAMPAIGN_GROUP_FOLDER_TXT

CI_CAMPAIGN_GROUP,COLUMN: CAMPAIGN_GROUP_NM

CI_CAMPAIGN_GROUP,COLUMN: CAMPAIGN_GROUP_CD

CI_TREATMENT,COLUMN: TREATMENT_VERSION_NO

CI_TREATMENT, COLUMN: END_DTTM

CI_TREATMENT,COLUMN: START_DTTM

CI_TREATMENT,COLUMN: CURRENT_VERSION_FLG

CI_TREATMENT,COLUMN: TREATMENT_REFERENCE_URL

CI_TREATMENT,COLUMN: TREATMENT_REFERENCE_URL

CI_TREATMENT,COLUMN: TREATMENT_NM

CI_TREATMENT,COLUMN: TREATMENT_CD



Contents of the %CI2LASR Macro Output Table

417

CHAR CHAR

CHAR

CHAR

CHAR CHAR

CHAR

CAMPAIGN_TYPE_CD

CAMPAIGN_TYPE_DESC

COMMUNICATION_RECURR_TYPE_DESC

COMMUNICATION_STATUS_DESC

CHANNEL_NM

MARKETING_CELL_CD

MARKETING_CELL_NM

240

128

240

1024

1024

1024

12

$240.

$128.

$240.

$1024.

$1024.

$1024.

$12.

$240.

$128.

$240.

$1024.

$1024.

$1024.

$12.

CI_MARKETING_CELL,COLUMN: MARKETING_CELL_NM

CI_MARKETING_CELL,COLUMN: MARKETING_CELL_CD

CI_CHANNEL,COLUMN: CHANNEL_NM

CI_COMMUNICATION_STATUS, COLUMN: COMMUNICATION_STATUS_DESC

CI_COMMUNICATION_RECURR_TYPE, COLUMN: COMMUNICATION_RECURR_TYPE_DESC

CI_CAMPAIGN_TYPE,COLUMN: CAMPAIGN_TYPE_DESC

CI_CAMPAIGN,COLUMN: CAMPAIGN_TYPE_CD


419

Appendix 6 REST API for SAS Decision Services Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Latency Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Other Important Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Decision Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Decision Services Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Decision Services Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Decision Services Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Validity Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 istrative Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Run-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Decision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Decision Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Decision Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Decision Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Decision Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Bindings (input and output) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Decision ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Time Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Guidance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Externally Defined Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 SAS Decision Services Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 Collection / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 Collection /decisionDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Collection /jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Resource /descisionDefinitions/{decisionID} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 Resource /decisions/{decisionId} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 Post-installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

420 Appendix 6 / REST API for SAS Decision Services

Overview This API allows access to decisions that are generated by the SAS Decision Services engine. Specifically, the API accepts inputs that are represented as decision parameters, processes them in the engine, and returns a representation of the decision generated. The API is implemented as a Representational State Transfer (REST) interface that accepts JSON payloads. The REST API generates decisions in the SAS Decision Services engine. To generate a decision, a client application posts a decision request object to a named decision definition and receives a decision in response. The request includes a set of bindings (one or more name-value pairs) that serve as inputs to the decision generation process. Each binding has a name that is a string and a value. The value might be a number, a Boolean value, a string, an array, or a table. The generated decision object contains a set of bindings that are used by the client applications to implement the decision. For example, a call center might use a decision that contains items to offer to a customer for sale. Each decision definition has a required set of bindings with fixed names and types for the decision request as well as a defined set of bindings for the corresponding decision object that was produced. A decision services engine might hold several decision flows. Each such flow contains code that generates a decision object when it is executed. Each flow is associated with only one decision definition that determines the inputs and outputs and that is an interface to the flow. The client application does not reference the flow directly. Rather, it uses the decision name that is defined in the decision definition. When a decision request is received by the engine, it looks up the decision definition with the supplied decision name, finds the flow that is associated with the decision definition, executes the flow, and returns the generated decision.

Latency Requirements In most cases, the decision must be returned to meet strict latency constraints (order of 10–100s of milliseconds) that require a synchronous call to the engine. In other cases, the client application does not care about the decision generated, relying instead on the side-effects of executing a decision flow. In this case, the client application can execute the decision flow asynchronously. The post returns immediately and does not block the client application. The side effects are completely determined by the decision flow.

Use Cases A typical use case is a call center application that sends information to the engine to determine the marketing offer to return to the caller. The call center application typically sends the caller's identification and some information that is not already available in the application's data storage (for example, the reason

Terminology

421

for the call). The engine might retrieve additional caller-specific information from the database and execute decision flows to generate the offer. Another use case might involve a website application that sends information to the engine in order to retrieve offer information that drives banner ments on the website. The decision is generated when creating content for the website and any delay in generating the page can cause the customer to leave the site. Therefore, a timely response within strict latency requirements is critical.

Other Important Features Here are additional important features of the REST API: 1

The decision is modeled as a transient resource that is created for every decision request. Therefore, there are no available GET methods to access decisions that have already been generated.

2

The representations for decisions and decision requests are implemented as separate media types.

3

The current implementation s only JSON payloads.

4

The POST method on the decisions collection returns a representation of generated decision synchronously.

5 The POST method on the jobs collection returns only an accepted status and

internally queues the decision flow for execution using the supplied decision request.

Terminology The following are applicable to the REST API for SAS Decision Services Transaction Processing as well as the Appendix 7, “SAS Decision Services istration,” on page 443.

Decision Services A collection of services that allow external and internal applications to generate decisions.

Decision Services Artifacts The operation of an engine is controlled by the set of artifacts that are loaded in the engine. These artifacts include decision definitions, decision flows, and variables. The artifacts are created using design-time services in a decision services environment.


Decision Services Engine The component of SAS Decision Services that implements run-time services to create decisions synchronously or accepts requests for creating decisions asynchronously. Engines are generally clustered to meet availability and scalability requirements.

Decision Services Environment A decision services environment offers services such as execution or run-time services, istrative services, and design-time services. These services are exposed as REST APIs. Although most of these APIs are used to create, manipulate, and use artifacts in a single decision services environment, some APIs allow the transfer of artifacts from one environment to another.

Validity Rules The artifacts in a decision services environment are complex objects that are created by design-time services. Parts of an artifact might depend on, or refer to, another part of the same artifact or another artifact. For example, a decision flow might contain a rule that uses a variable, also contained in the same decision flow. The variable might get its value from a binding in a decision definition that the decision flow refers to. In the latter case, the decision flow is considered to be dependent on the decision definition. Validity rules determine whether the contents of a single artifact is consistent in itself as well as across artifacts. In other words, in the above example, the variable that is referenced in the rule must not only exist in the decision flow, but must also be used in the rule that is consistent with its data type. Therefore, if the type of the variable is string, the rule might not use it as an integer. In addition, the binding in the decision definition that supplies the value to the variable must exist and match the type of the variable.

istrative Services A subset of the decision services that focuses on istering a decision services environment. In particular, it includes activating or de-activating decision flows, changing the time-out values, and changing the value of variables in the engines that are contained in the environment.

Activation Activation makes the decision flows available for execution in a decision services engine or engines. Active decision flows can be executed to create decisions by sending decision requests to the engine. Not all decision flows can be activated. Only a decision flow that (by itself and the artifacts that it depends on) satisfies validity rules can be activated. Since artifacts are modified through the design-time API, and moved to and from an environment using a promotion API. The istration API provides error messages that direct the to one of these APIs in case validity errors are encountered during activation.

Terminology

423

Run-time Services A subset of the decision services that focuses on the execution of decision flows.

Decision The output of the SAS Decision Services engine, generated by executing a decision flow. It includes a set of bindings, such as name-value pairs that contain the output that is generated by executing the decision flow. In addition, it contains diagnostic information, such as timestamps that mark the start and end of the decision-making process and a correlation ID that was supplied with the decision request.

Decision Request The input to execute a decision flow in the SAS Decision Services engine. It also includes a set of bindings, such as name-value pairs that are written to the decision flow in order to create the decision. In addition, it contains information, such as the Internet Assigned Numbers Authority (IANA) time zone of the client, that might be used to interpret clock time in the engine. It also contains the correlation ID for tracking the request through the engine. It can also contain the simulation timestamp and simulation time zone information. The latter two values are optional. However, they might be required by certain decision flows.

Decision Flow A set of rules and logic that is executed in the SAS Decision Services engine when a decision request is received.

Decision Variable The decision variables are named and typed values that influence the execution of decision flows in the SAS Decision Services engines. The value of a variable for a particular environment can be changed using the istration API for that environment. Variables are global in scope, for a particular environment. These variables affect the execution of all decision flows in the environment.

Decision Definition Named metadata that describes the input and output bindings for the decision request and decision. The decision definition captures the external contract of the decision flow. It determines the names and types of input data that is expected by the flow, and that are to be supplied in a decision request. It also determines the names and types of data that is contained in the decision that the flow generates.

Bindings (input and output) A set of name-value pairs that is used to represent data as part of the decision (output) or the decision request (input). The names and the type of

424 Appendix 6 / REST API for SAS Decision Services corresponding value are defined in the decision definition. The name is usually chosen by the person who designs the decision definition, and it reflects the domain-specific . For example, it is possible to have a value called customerId of type string.

Decision ID The name of the decision definition. The client application does not reference the decision flow directly. Instead, it uses the decision ID (the URL-encoded name of the decision definition) to request a decision to be created. This separates the client application from the actual execution logic, allowing the latter to be swapped out for another decision flow, without bringing the system down.

Time Out Since, in most cases, it is critical to generate a decision within strict time limits, a decision definition can have a time-out value associated with it that causes the engine to time out if it fails to finish executing the decision flow within that time. The time-out values are specified in seconds in REST APIs.

Job A collection that allows asynchronous execution of decision flows in the engine. The client application posts the decision request to this collection, and the engine queues a decision for execution using the decision request. As soon as the execution is queued, the engine returns a status of Accepted to the client application.

Pagination Overview Pagination establishes the baseline expected query parameters and behavior for paging or iterating through collections. For collections, APIs can use query parameters to fetch (GET) or update (PUT, PATCH) subsets of collections. This helps prevent the transmission of entire (large) collections across networks, when a client application can visit or present only a small subset of the collection. …collection?start= &limit=<max-item-count> …collection?start= …collection?limit=<max-item-count>

APIs should use the start value to indicate the starting index of the subset. Start should be a zero-based index. The default start should be 0. APIs should use the limit value as the maximum number of items to return. The number of items returned can be less, if the collection is exhausted. APIs should use a default limit of 10. Collection results should use hypermedia controls for the following, if each such collection subset or page navigation is possible and practical.

Media Types

425

n first (rel="first") n previous (rel="prev") n next (rel="next") n last (rel="last")

The query result uses the collection format described in “application/ vnd.sas.collection” on page 425. The collection result must omit the rel="next" link if the collection has been exhausted. This means that there are no more items. If the pagination is at the beginning of the collection, the API must omit the rel="prev" link. The collection object can contain an integer count attribute, if the collection size is known.

Guidance When a resource representation contains links to collections, those links should go to the main collection without the query parameters. The server should apply the default start and limit values to return the first page. The API can also include a field that contains the number of items in the collection. By convention, this is named itemCount for the corresponding .../items collection. If you want to view all of the objects within the collection, use at least the total number of objects as the value of limit. Pagination should be the default, to prevent the possibility of reading large collections. Requests for collection resources return an empty collection, if there are no items that match the criteria. For example, if the start value is more than the number of items in the collection, an empty collection is returned. This could happen if resources are deleted while someone is paging through the collection using the next or previous links that were constructed when the resources were still available. This is not an error condition and does not generate an error response.

Media Types Externally Defined Media Types application/vnd.sas.collection application/vnd.sas.collection denotes a collection of resources. The collection should contain domain objects in the element named items. This allows heterogeneous collection and uniform structure across different collections. It should have a name attribute that is the domain-specific name for the collection items. The default is "items." If approved by the API COE, an API can use a different name for the container. The value of the accept attribute, if present, must be a text string consisting of a space-separated list of media type strings. The media type names can omit the +xml and +json. The type is implicit in the response representation of the collection. It should contain the values of the start and index of the collection's subset of elements, as per the pagination query parameters (&start=int and &limit=int), or the collection's default start (0) and limit (10). The type of start is a 64-bit signed integer value. The type of limit is a 32-bit signed integer value. The collection can include an integer count attribute if the API can efficiently compute the size

426 Appendix 6 / REST API for SAS Decision Services of the underlying collection. The type of the count is a 64-bit signed integer value. The collection can have a nested collection of links. Each link element in the links collection must be represented according to REST API link representation standards. Here is an example of application/vnd.sas.collection+json and application/ vnd.sas.collection+json;version=2: { "version" : 2, "accept": "space-separated media type names allowed in this collection", "count" : integer, "start" : integer, "limit" : integer, "name" : "items", "items": [ { resource1 fields }, ..., { resourceN fields } ], "links" : [ { link representation }, ... { link representation }, ] }

Note: The order of the fields can vary. Here is an example of application/vnd.sas.collection+xml and application/ vnd.sas.collection+xml;version=2 ... ... ...

Note: The order of the fields can vary.

SAS Decision Services Media Types application/vnd.sas.decision.definition The application/vnd.sas.decision.definition media type describes the inputs that are required to execute a decision flow and outputs that are generated by it. It describes the data that can be used to construct the input member of the decision request and render the data that is contained in the output member of

Media Types

427

the created decision. The value of the decisionId field is used as a key to execute decision flows synchronously, as well as asynchronously. When returned by the run-time services, it represents a decision definition of a decision flow deployed in the engine. When returned by the design services, it represents a decision definition that can be edited and used to construct decision flow. The latter case is not addressed by this API. Here are the link relations for the application/vnd.sas.decision.definition media type. Relationship

HTTP Method

Description

self

GET

The link to the summary of this decision definition. URI: SASDecisionServices/rest/ runtime/decisionDefinitions/ {decisionId} Media type: application/ vnd.sas.decision.definition.summa ry

self

GET

The link to itself. URI: SASDecisionServices/rest/ runtime/decisionDefinitions/ {decisionId} Media type: application/ vnd.sas.decision.definition

create

POST

The link to create a decision by executing the decision flow associated with the underlying decision definition. URI: SASDecisionServices/rest/ runtime/decisions/{decisionId} Media type: application/ vnd.sas.decision.request

execute

POST

The link to create a job that executes the decision flow that is associated with the underlying decision definition. Use this to execute a decision flow asynchronously (for example, without waiting for it to finish). URI: SASDecisionServices/rest/ runtime/jobs? decisionId={decisionId} Media type: application/ vnd.sas.decision.request

The application/vnd.sas.decision.definition media type contains the following . Name

Type

Description

version

integer

The media type's schema version number.

428 Appendix 6 / REST API for SAS Decision Services Name

Type

Description

decisionID

string

The ID or name of the underlying decision definition.

description

string

Short description of the decision definition as entered by the creator of the resource.

created

dateTime

The timestamp that shows when this resource was first created.

modified

dateTime

The timestamp of when this resource was last modified.

inputs

object

This is a set of bindings such as an unordered set of name-value pairs that describe the data that is accepted by the decision flow. It can be used to construct the input member of the decision request when executing a flow. The name part of the binding is a string that represents the name of a field. The value is a string that is the type of data the decision request would contain for that field. The valid types are described below. Although the decision definition contains only the name and type of a field, the description below also addresses how the data of the corresponding type would look as part of the decision request. SAS Decision Services s data values of the following primary types: n Boolean — This is a Boolean value that includes true,

false, or null.

n integer — This is a 32-bit signed two's complement

integer value including null representing a missing value.

n decimal — This is a double-precision 64-bit format

IEEE 754 value including "Infinity", "-Infinity", * "NaN", and null representations.

n string — This is a character string that can be empty

or null.

n dateTime — This is a timestamp value, with the

accuracy of milliseconds that can be null. In JSON, this is represented as a string in ISO8601 format. In XML, it is represented as the dateTime type.

Single dimensional arrays or lists of the above types are also ed. Here are the corresponding types: n booleanArray n integerArray n decimalArray n stringArray n dateTimeArray

Media Types

429

Name

Type

Description

inputs (continued)

object

A table type is also ed. A table is a dynamic type that contains self-describing metadata determining the name and type of data for each column. Table data is represented as an array of two objects: the metadata object and the data object. The metadata element must precede the data element because it is often easier to parse the metadata before the data. Therefore, the parsing code is smaller and simpler for the client. The objects are described below: metadata Contains an ordered collection of column metadata that includes the name and a string representing the type of the column, as described above. The type of the column can be one of the primary types described above. Array types and nested tables are not ed. data Contains an ordered collection of values representing the data values of the table, in row major order. For example, the outer collection represents a collection of rows and the inner collection represents a single row of the table. The values in each row must match the type of the columns in the order described in the metadata object above.

outputs

object

This is a set of bindings such as an unordered set of name-value pairs that describe the data returned by the decision flow. It can be used to interpret the output member of the decision when executing a flow. The ed types are identical to those described in the inputs section. See the inputs member above for details.

links

collection of link objects

One or more link objects. See the link relations information above for a description of the link types.

Here is an example of application/vnd.sas.decision.definition+json: { "decisionId": "Sample Offers", "description": "This is a sample decision definition summary.", "created" : "2014-01-27T12:32:12.345Z", "modified" : "2014-01-27T12:32:12.345Z", "inputs" : { "aBoolean" : "boolean", "anInt" : "integer", "aFloat" : ""decimal", "aString" : "string", "aDateTime" : "dateTime", "aBooleanArray" : "booleanArray", "aIntArray" : "integerArray", "aFloatArray" : "decimalArray", "aStringArray" : "stringArray", "aTimestampArray" : "dateTimeArray" "aTable" : "table" }, "outputs" : {

430 Appendix 6 / REST API for SAS Decision Services "aBoolean" : "boolean", "anInt" : "integer", "aFloat" : ""decimal", "aString" : "string", "aDateTime" : "dateTime", "aBooleanArray" : "booleanArray", "aIntArray" : "integerArray", "aFloatArray" : "decimalArray", "aStringArray" : "stringArray", "aTimestampArray" : "dateTimeArray" "aTable" : "table" }, "links": [{ "method": "GET", "rel": "self", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/decisionDefinitions/Sample%20Offers", "uri": "decisionDefinitions/Sample%20Offers", "type": "application/vnd.sas.decision.definition" }, { "method": "GET", "rel": "summary", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/decisionDefinitions/Sample%20Offers", "uri": "decisionDefinitions/Sample%20Offers", "type": "application/vnd.sas.decision.definition.summary" }, { "method": "POST", "rel": "decisions", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/decisions/Sample%20Offers", "uri": "decisions/Sample%20Offers", "type": "application/vnd.sas.decision" }, { "method": "POST", "rel": "jobs", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/jobs/Sample%20Offers", "uri": "jobs/Sample%20Offers" }] }

application/vnd.sas.decision.definition.summary Summary information for the underlying decision definition that is returned as part of a collection to browse functionality that does not require retrieving the entire decision definition. This information might be returned by the run-time services. In that case, the underlying resource has been deployed and is not editable. Here are the link relations for the application/ vnd.sas.decision.definition.summary media type.

Media Types

431

Relationship

HTTP Method

Description

self

GET

The link to the summary of this decision definition. URI: SASDecisionServices/rest/ runtime/ decisionDefinitions/ {decisionId} Media type: application/ vnd.sas.decision.definition. summary

self

GET

The link to itself. URI: SASDecisionServices/rest/ runtime/ decisionDefinitions/ {decisionId} Media type: application/ vnd.sas.decision.definition

create

POST

The link to create a decision by executing the decision flow that is associated with the underlying decision definition. URI: SASDecisionServices/rest/ runtime/decisions/ {decisionId} Media type: application/ vnd.sas.decision.request

execute

POST

The link to create a job that executes the decision flow that is associated with the underlying decision definition. Use this to execute a decision flow asynchronously (for example, without waiting for it to finish). URI: SASDecisionServices/rest/ runtime/jobs? decisionId={decisionId} Media type: application/ vnd.sas.decision.request

The application/vnd.sas.decision.definition.summary media type contains the following .


Type

Description

version

integer


decisionID

string


description

string

Short description of the decision definition as entered by the creator of the resource.

created

dateTime

The timestamp of when this resource was first created.

modified

dateTime

The timestamp that shows when this resource was last modified.

links



Here is an example of application/vnd.sas.decision.definition.summary+json: { "decisionId": "Sample Offers", "description": "This is a sample decision definition summary.", "created" : "2014-01-27T12:32:12.345Z", "modified" : "2014-01-27T12:32:12.345Z", "links": [{ "method": "GET", "rel": "self", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/decisionDefinitions/Sample%20Offers", "uri": "decisionDefinitions/Sample%20Offers", "type": "application/vnd.sas.decision.definition.summary" }, { "method": "GET", "rel": "detail", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/decisionDefinitions/Sample%20Offers", "uri": "decisionDefinitions/Sample%20Offers", "type": "application/vnd.sas.decision.definition" }, { "method": "POST", "rel": "decisions", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/decisions/Sample%20Offers", "uri": "decisions/Sample%20Offers", "type": "application/vnd.sas.decision" }, {

Media Types

433

"method": "POST", "rel": "jobs", "href": "http://rdcesx13020.race.sas.com/SASDecisionServices/rest/ runtime/jobs/Sample%20Offers", "uri": "jobs/Sample%20Offers" }] }

application/vnd.sas.decision The application/vnd.sas.decision media type describes the decision as returned by the SAS Decision Services engine when a decision request is posted to the decisions resource collection. The application/vnd.sas.decision media type contains the following . Name

Type

Description

version

integer


correlationId

string

A string value that is supplied through the decision request and that can be used to correlate the request and the decision that is generated. The engine also uses this string in the log to identify errors or execution trace statements that are associated with the generation of the decision object.

startTimestamp

dateTime

Server timestamp that shows when the engine started generating the decision.

endTimestamp

dateTime

Server timestamp that shows when the engine completed generating this decision.

outputs

object

This is a set of bindings such as an unordered set of name-value pairs that are a part of the decision. The names correspond to the binding names that are described in the outputs member of decision definition. The value contains data of the corresponding type. The valid values are described in the inputs member of application/ vnd.sas.decision.definition.

434 Appendix 6 / REST API for SAS Decision Services Here is an example of application/vnd.sas.decision+json: { "correlationId" : "ABCD", "startTimestamp" : "2008-11-20T12:40:53.007-05:00", "endTimestamp" : "2008-11-20T12:40:53.007-05:00", "outputs" : { "aBoolean" : true, "anInt" : 111, "aFloat" : 1.11, "aString" : "String1", "aDateTime" : "2007-07-13T14:32:07.000Z", "aNullValue" : null, "aBooleanArray" : [ true, false, true ], "aIntArray" : [ 111, 222, 333 ], "aFloatArray" : [ 1.11, 2.22, 3.33 ], "aStringArray" : [ "String1", "String2", "String3" ], "aTimestampArray" : [ "2007-07-13T14:32:07.000Z", "2007-02-13T14:32:07.000Z", "2007-02-13T00:00:00.000Z" ] "aBooleanArrayWithANullItem" : [ true, false, null ], "aTable" : [{ "metadata" : [ { "aStringColumn" : "string" }, { "anIntColumn" : "int" }, { "aFloatColumn" : "float" }, { "aBooleanColumn" : "boolean" }, { "aTimestampColumn" : "timestamp" }] }, { "data" : [[ "one", 1, 1.11, true, "2001-01-01T01:01:01.000Z" ], [ "two", 2, 2.22, false, "2002-02-02T02:02:02.000Z" ], [ "three", 3, 3.33, true, "2003-03-03T03:03:03.000Z" ], [ "four", 4, 4.44, false, "2004-04-04T04:04:04.000Z" ], [ "five", 5, 5.55, true, "2005-05-05T05:05:05.000Z" ], [ null, null, null, null, null ]] }], "aTableWithNoData" : [{ "metadata" : [ { "aStringColumn" : "string" }, { "anIntColumn" : "int" }, { "aFloatColumn" : "float" }, { "aBooleanColumn" : "boolean" }, { "aTimestampColumn" : "timestamp" }] }, { "data" : [] }], "aNullValuedTable" : null } }

application/vnd.sas.decision.request The application/vnd.sas.decision.request media type represents the information that is used to generate the decision. The application/vnd.sas.decision.request media type contains the following .

Media Types

435

Name

Type

Description

version

integer


correlationId

string

A string value that is supplied through the decision request and that can be used to correlate the request and the decision that is generated. The engine also uses this string in the log to identify errors or execution trace statements that are associated with the generation of this decision object. This value is same as in the vnd.sas.decision media type.

clientTimeZone

string

A string that contains the time zone of the client that requests the decision, as defined in the IANA time zone database. This value can be used by the decision flow to evaluate datetime values in the client's time zone for the purpose of generating a decision.

inputs

object

This is a set of bindings such as an unordered set of name-value pairs. The names correspond to the binding names that are described in the inputs member of the decision definition. The value contains the data of the corresponding type. The valid values are described in the outputs member of application/ vnd.sas.decision.definition.

Here is an example of application/vnd.sas.decision.request+json: { "version" : "1" "correlationId" : "ABCD", "clientTimeZone" : "Asia/Kolkata", "inputs" : { "aBoolean" : true, "anInt" : 111, "aFloat" : 1.11, "aString" : "String1", "aDateTime" : "2007-07-13T14:32:07.000Z", "aNullValue" : null,

436 Appendix 6 / REST API for SAS Decision Services "aBooleanArray" : [ true, false, true ], "aIntArray" : [ 111, 222, 333 ], "aFloatArray" : [ 1.11, 2.22, 3.33 ], "aStringArray" : [ "String1", "String2", "String3" ], "aTimestampArray" : [ "2007-07-13T14:32:07.000Z", "2007-02-13T14:32:07.000Z", "2007-02-13T00:00:00.000Z" ] "aBooleanArrayWithANullItem" : [ true, false, null ], "aTable" : [{ "metadata" : [ { "aStringColumn" : "string" }, { "anIntColumn" : "int" }, { "aFloatColumn" : "float" }, { "aBooleanColumn" : "boolean" }, { "aTimestampColumn" : "timestamp" }] }, { "data" : [[ "one", 1, 1.11, true, "2001-01-01T01:01:01.000Z" ], [ "two", 2, 2.22, false, "2002-02-02T02:02:02.000Z" ], [ "three", 3, 3.33, true, "2003-03-03T03:03:03.000Z" ], [ "four", 4, 4.44, false, "2004-04-04T04:04:04.000Z" ], [ "five", 5, 5.55, true, "2005-05-05T05:05:05.000Z" ], [ null, null, null, null, null ]] }], "aTableWithNoData" : [{ "metadata" : [ { "aStringColumn" : "string" }, { "anIntColumn" : "int" }, { "aFloatColumn" : "float" }, { "aBooleanColumn" : "boolean" }, { "aTimestampColumn" : "timestamp" }] }, { "data" : [] }], "aNullValuedTable" : null } }

Resources Collection / The / returns a collection of links to the top-level collections surfaced through this API. Authentication is not required. The request URL is GET http:// www.example.com/SASDecisionServices/rest/runtime/. The response to the GET request is a collection of top-level links that are returned to decisionDefinitions for resources that run-time services. Currently only a single collection is returned. Here are the HTTP response codes: 200 OK

Resources 437

404 Not found. 500 Server error. This resource can return the following media type representations by setting the Accept: header of the request: n application/json n application/vnd.sas.collection+json

Collection /decisionDefinitions The /decisionDefinitions collection is a collection of decision definitions that are associated with the corresponding decision flows that are deployed in the SAS Decision Services engine. The collection s pagination and filtering by the name of the decision definition. Because the names of decision definitions that are deployed in a SAS Decision Services engine are unique, using such a filter returns a collection of at most one item. The decision definition summary objects contain links that allow the execution of the decision flow synchronously and asynchronously. It is also possible to retrieve the complete decision definition. Authentication is not required. The GET request URL is GET http://www.example.com/SASDecisionServices/ rest/runtime/decisionDefinitions. Here are the HTTP response codes: 200 OK 404 Not found. 500 Server error. Here are the query parameters for /decisionDefinitions: Name

Type

Description

start

integer

The starting index of the first decision definition summary on a page. The index is 0-based. The default is 0.

limit

integer

The maximum number of decision definition summary objects to return on this page of results. The actual number of returned decision definition summary objects might be less, if the collection has been exhausted. The default is 10.


Type

Description

name

string

This filters by the name of the decision definition. The names of decision definitions are unique. Therefore, this returns a collection of at most one item.

Here is a JSON representation of the decisionDefinitionSummaries collection: { "decisionDefinitionSummaries": [ { application/vnd.sas.decision.definition.summary contenti }, { application/vnd.sas.decision.definition.summary contenti+1 }, ... { application/vnd.sas.decision.definition.summary contentn }, ], "accept": "application/vnd.sas.decision.definition.summary" "links: [ { "rel" : "first", "method" : "GET", ... }, { "rel" : "prev", "method" : "GET", ... }, { "rel" : "next", "method" : "GET", ... }, { "rel" : "last", "method" : "GET", ... } ] }

This resource can return the following media type representations by setting the Accept: header of the request: n application/json n application/vnd.sas.collection+json

Collection /jobs The /jobs collection is a collection of resources that represent transient requests to asynchronously execute decision flows. When a decision.request object is posted to this URL along with a URL parameter that contains the decisionId of the decision definition that is associated with a decision flow, the SAS Decision Services engine accepts this request and returns a status of 202 Accepted. It then creates a job that represents a request to execute the decision flow asynchronously. The client application does not wait for the flow to execute or even for the job to be created. Because a job is a transient resource, it is not possible to retrieve a job object using a GET method. Authentication is not required. The POST URL is POST http://www.example.com/SASDecisionServices/rest/ runtime/jobs. Here are the HTTP response codes: 200 OK 404 Not found.

Resources 439

500 Server error. Here is the query parameter for /jobs: Name

Type

Description

decisionID

string

The ID of the decision definition that is associated with the decision flow to be executed asynchronously.

This method can return the following content type, as named by the ContentType: header: n application/vnd.sas.decision.request+json

Resource /descisionDefinitions/{decisionID} The /decisionDefinitions/{decisionId} resource represents a single decision definition that is associated with a decision flow that is deployed in the SAS Decision Services engine. The GET request returns a single decision definition as identified by either the decisionId or the corresponding decision definition summary object, depending on the media type that is requested. The GET request URL is GET http://www.example.com/SASDecisionServices/ rest/runtime/decisionDefinitions/{decisionId}. Authentication is not required. Here are the HTTP response codes: 200 OK 404 Not found. 500 Server error. This resource can return the following media type representations by setting the Accept: header of the request: n application/json n application/vnd.sas.decision.definition+json n application/vnd.sas.decision.definition.summary+json

Here is the query parameter for /jobs: Name

Type

Description

decisionID

string

The URL encoded name of the decision definition.


Resource /decisions/{decisionId} The /decisions/{decisionId} resource is a transient resource that is used to execute decision flows in the SAS Decision Services engine. The decision resource is created when a decision.request object is posted at the URL below. The resource that is created is not persisted and cannot be retrieved using a GET method. Therefore, after generation by using a separate GET method, decisions cannot be accessed. The POST method returns the decision object in the response body and does not return a location for the created decisions. It executes a decision flow that is associated with a decision definition that is identified by the decisionId. Authentication is not required. The POST URL is POST http://www.example.com/SASDecisionServices/rest/ runtime/decisions/{decisionId}. Here are the HTTP response codes: 200 OK 404 Not found. 500 Server error. This method can return the following content type, as named by the ContentType: header: n application/vnd.sas.decision.request+json

This resource can return the following media type representations by setting the Accept: header of the request: n application/vnd.sas.decision.definition+json

Post-installation Steps In order to for the REST API to work correctly, the following post-installation steps must be completed: 1

Find the sas.conf file in the conf folder of the SAS web server installation <SAS-configuration-directory>\Web\WebServer\conf.

2

Find the two lines of code that define the proxy and reverse proxy for the SAS Decision Services engine.

Proxy /RTDM balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /RTDM balancer://<machine name>.na.sas.com_Cluster7/RTDM 3 Copy these lines of code to a text editor and change the /RTDM on the right

side of the mapping to /SASDecisionServices as follows: Proxy /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM 4 Paste these modified lines of code directly below the lines mapping /RTDM. Proxy /RTDM balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /RTDM balancer://<machine name>.sas.com_Cluster7/RTDM

Resources 441 Proxy /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM ProxyReverse /SASDecisionServices balancer://<machine name>.na.sas.com_Cluster7/RTDM 5 After editing the file, restart the SAS web server.


443

Appendix 7 SAS Decision Services istration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Externally Defined Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 SAS Decision Services Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 Resources and Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resource / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Collection /decisionDefinitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Collection /decisionFlows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Collection /variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

458 458 460 466 472

Overview The SAS Decision Services istration API is a REST API that isters a SAS Decision Services deployment containing one or more SAS Decision Services engines. Decision flows that are loaded in the engine for execution are known as active decision flows. The process of making a decision flow active is known as activation. Conversely, making it unavailable is known as deactivation. Not all decision flows can be activated. Only decision flows that are valid can be activated. The validity rules are described in the terminology section. The istration API allows activation of valid decision flows and deactivation of any active decision flow. The istration API does not modifying artifacts such as decision flows, or adding missing artifacts from other decision services deployments. So, if activation fails because of validity reasons, the istration API returns detailed validation error messages. These messages can then be used to correct the situation by using the appropriate API. In most cases in the engine, the decision must be generated under strict latency constraints. Every decision flow in the engine is associated with a decision definition that contains a time-out value. This time-out value is used by the engine to terminate the decision flow execution, should it take more time to

444 Appendix 7 / SAS Decision Services istration generate the decision. The istrative API allows setting and changing the time-out value of the decision definition. Some decision flows can be associated with a variable whose value can affect the execution of the decision flow and, accordingly, the decision generated by it. The istration API also makes it possible to change the value of variables.

Use Cases Here are use cases for the SAS Decision Services istration API: Query the status of flows in the engine You might want to select a group of flows based on certain filter criteria and view their contents. The filter criteria might include selection by created or modified date, name, ID, activation status, association with a particular decision definition, association with a particular variable, or a combination of those. Decision flows in general are large resources and, for the purpose of istration, a summary representation is more helpful. Activation or deactivation You might want to select a group of inactive flows based on filter criteria, as above, and activate or deactivate one or all of them. Changing time-out values You might want to select a decision definition and view or change its time-out value. Again, a summary representation of the decision definition is more useful. Changing the value of a variable You might want to select a variable using filter criteria and view or change its value. The filter criteria might include an association with a particular flow.

Terminology For terminology specific to REST APIs, see “Terminology” on page 421.

Media Types Externally Defined Media Types application/vnd.sas.collection For more information about this media type, see “application/vnd.sas.collection” on page 425.

Media Types

445

SAS Decision Services Media Types application/vnd.sas.decision.definition.summary Summary information for the underlying decision definition is returned as part of a collection. This makes it possible to browse functionality that does not require retrieving the entire decision definition. This information might be returned by the run-time services. In that case, the underlying resource has been deployed and is not editable. When exposed by the design-time services links, it includes those that help create, edit, and delete decision definition resources. When returned by the istration services, it represents a decision definition that is available in the engine that is associated with a decision flow that might or might not be active. Here are the link relations for the application/ vnd.sas.decision.definition.summary media type. Relationship

HTTP Method

Description

self

GET

The link to the summary of this decision definition. Available in the Execution API. URI: /rest/ decisionDefinitions/ {decisionId} Media type: application/ vnd.sas.decision.definition. summary

self

GET

The link to itself. Available in the Execution API and istration API. URI: /rest/ decisionDefinitions/ {decisionId} Media type: application/ vnd.sas.decision.definition

create

POST

The link to create a decision by executing the decision flow that is associated with the underlying decision definition. Available in the Execution API and istration API. URI: /rest/decisions/ {decisionId} Media type: application/ vnd.sas.decision.request

446 Appendix 7 / SAS Decision Services istration Relationship

HTTP Method

Description

execute

POST

The link to create a job that executes the decision flow that is associated with the underlying decision definition. Use this to execute a decision flow asynchronously (for example, without waiting for it to finish). Available in the Execution API and istration API. URI: SASDecisionServices/rest/ runtime/jobs? decisionId={decisionId} Media type: application/ vnd.sas.decision.request

timeOut

GET

The link to return a floating point number for the time out, in seconds, for this decision definition. If the value is not set, an empty document is returned. If the API does not this value, a Not Found or 404 error is returned. Available in the istration API. URI: /rest/ decisionDefinitions/ {decisionId}/timeOut Media type: text/plain

timeOut

PUT

The link to update the time out, in seconds, for this decision definition. Acceptable values are a positive floating point number or an empty document. The latter clears the value. If the API does not this value, a Not Found or 404 error is returned. Available in the istration API. URI: /rest/ decisionDefinitions/ {decisionId}/timeOut Media type: text/plain

Media Types

447

Relationship

HTTP Method

Description

timeOutEnabled

GET

The link to return a Boolean expression indicating whether the time out is enabled for the decision definition. If the value is not set, an empty document is returned. If the API does not this value, a Not Found or 404 error is returned. Available in the istration API. URI: /rest/ decisionDefinitions/ {decisionId}/ timeOutEnabled Media type: text/plain

timeOutEnabled

PUT

The link to update the timeOutEnabled field of this decision definition. Acceptable values are a Boolean expression or an empty document. The latter clears the value. If the API does not this value, a Not Found or 404 error is returned. Available in the istration API. URI: /rest/ decisionDefinitions/ {decisionId}/ timeOutEnabled Media type: text/plain

The application/vnd.sas.decision.definition.summary media type contains the following . Name

Type

Description

version

integer


id

string

The system-assigned unique ID for this object.

decisionID

string


label

string

The descriptive or display name of the underlying decision definition.

448 Appendix 7 / SAS Decision Services istration Name

Type

Description

description

string

The short description of the decision definition as entered by the creator of the resource.

created

dateTime

The timestamp that shows when this resource was first created.

modified

dateTime


lastModifiedBy

string

The name of the who last modified the resource.

timeOutEnabled

Boolean

It is true, if the time out for this decision definition is enabled. It is false, if otherwise.

timeOut

decimal

The value of the time out in seconds.

links



Here is an example of application/vnd.sas.decision.definition.summary+json: { "version": 1, "decisionId": "Sample Offers", "description": "This is a sample decision definition summary.", "created" : "2014-01-27T12:32:12.345Z", "modified" : "2014-01-27T12:32:12.345Z", "links": [{ "method": "GET", "rel": "self", "href": "http://<server>/SASDecisionServices/ rest/runtime/decisionDefinitions/Sample%20Offers", "uri": "decisionDefinitions/Sample%20Offers", "type": "application/vnd.sas.decision.definition.summary" }, { "method": "GET", "rel": "detail", "href": "http://<server>/SASDecisionServices/ rest/runtime/decisionDefinitions/Sample%20Offers", "uri": "decisionDefinitions/Sample%20Offers", "type": "application/vnd.sas.decision.definition" }, { "method": "POST", "rel": "decisions", "href": "http://<server>/SASDecisionServices/

Media Types

449

rest/runtime/decisions/Sample%20Offers", "uri": "decisions/Sample%20Offers", "type": "application/vnd.sas.decision" }, { "method": "POST", "rel": "jobs", "href": "http://<server>/SASDecisionServices/ rest/runtime/jobs/Sample%20Offers", "uri": "jobs/Sample%20Offers" }] }

application/vnd.sas.decision.flow.summary The application/vnd.sas.decision.flow.summary media type is a summary representation of a decision flow. Here are the link relations for the application/vnd.sas.decision.flow.summary media type. Relationship

HTTP Method

Description

self

GET

The link to itself. Available in the istration API. URI: /rest/decisionFlows/ {decision flow id} Media type: application/ vnd.sas.decision.flow.sum mary

decisionDefinition

GET

The link to the decision definition of this decision flow. Available in the istration API. URI: /rest/ decisionDefinitions/ {decision id} Media type: application/ vnd.sas.decision.definition. summary

active

GET

The link to return a Boolean expression that indicates whether the decision flow is active. If the API does not this value, a Not Found or 404 error is returned. Available in the istration API. URI: /rest/decisionFlows/ {decision flow id}/active Media type: text/plain

450 Appendix 7 / SAS Decision Services istration Relationship

HTTP Method

Description

active

PUT

The link to update the active field of this decision flow. Acceptable values are a Boolean expression. If the API does not this value, a Not Found or 404 error is returned. Available in the istration API. URI: rest/decisionFlows/ {decision flow id}/active Media type: text/plain

The application/vnd.sas.decision.flow.summary media type contains the following . Name

Type

Description

version

integer


id

string


label

string

The descriptive or display name of the underlying decision flow.

description

string

The short description of the decision flow, as entered by the creator of the resource.

created

dateTime


modified

dateTime


lastModifiedBy

string


decisionID

string

The ID or name of the associated decision definition.

active

Boolean

This is true if the flow has been activated. Otherwise, this is false.

Media Types

451

Name

Type

Description

links



Here is an example of application/vnd.sas.decision.flow.summary: { "version": 1, "id": "AM4OPKD4J0HCIAAA", "description": "ExitPopupNoUCH:PerformanceTestFlows:CMDM Performance:", "label" : "ExitPopupNoUCH:PerformanceTestFlows:CMDM Performance" "created" : "2008-11-18T15:25:22.535+00:00", "modified" : "2008-11-18T15:25:22.535+00:00", "lastModifiedBy" : "prasen", "decisionId" : "ExitPopupNoUCHEvent", "active" : "true", "links": [{ "method": "GET", "rel": "self", "href": "http://<server>/SASDecisionServicesistration/ rest/decisionFlows/AM4OPKD4J0HCIAAA", "uri": "decisionFlows/AM4OPKD4J0HCIAAA", "type": "application/vnd.sas.decision.flow.summary" }, { "method": "GET", "rel": "decisionDefinition", "href": "http://<server>/SASDecisionServicesistration/ rest/decisionDefinitions/ExitPopupNoUCHEvent", "uri": "decisionDefinitions/ExitPopupNoUCHEvent", "type": "application/vnd.sas.decision.definition.summary" }, { "method": "GET", "rel": "active", "href": "http://<server>/SASDecisionServicesistration/ rest/decisionFlows/AM4OPKD4J0HCIAAA/active", "uri": "decisionFlows/AM4OPKD4J0HCIAAA/active", "type": "text/plain" }, { "method": "PUT", "rel": "active", "href": "http://<server>/SASDecisionServicesistration/ rest/decisionFlows/AM4OPKD4J0HCIAAA/active", "uri": "decisionFlows/AM4OPKD4J0HCIAAA/active", "type": "text/plain" }] }

application/vnd.sas.decision.variable The application/vnd.sas.decision.variable media type represents a variable in SAS Decision Services.

452 Appendix 7 / SAS Decision Services istration Here are the link relations for the application/vnd.sas.decision.variable media type. Relationship

HTTP Method

Description

self

GET

The link to itself. Available in the istration API. URI: /rest/variables/ {variable id} Media type: application/ vnd.sas.decision.variable

value

GET

The link to return a representation for the value field of the variable. The representation of the value is described in the member’s information below. The value is represented as a collection of strings that contain literal expressions. For array type, each value corresponds to the value that is assigned to that element of the array. Nonarray variables use only the first element. Available in the istration API. URI: /rest/variables/ {variable id}/value Media type: application/ vnd.sas.collection+json, application/ vnd.sas.collection+xml

value

PUT

The link to update the value field of the variable. . Available in the istration API. URI: /rest/variables/ {variable id}/value Media type: application/ vnd.sas.collection+json, application/ vnd.sas.collection+xml

The application/vnd.sas.decision.variable media type contains the following . Name

Type

Description

version

integer


id

string


Media Types

453

Name

Type

Description

label

string

The descriptive or display name of the underlying variable.

description

string

The short description of the variable, as entered by the creator of the resource.

created

dateTime


modified

dateTime


lastModifiedBy

string


type

string

The type of variable.

links



value

array of strings

The value of the underlying variable as an array of strings. Each element corresponds to a literal expression that is evaluated to get the value of that element. Non-array variables require a single element. Array variables can use more than one element.

Here is an example of application/vnd.sas.decision.variable: { "version": 1, "id": "GVStringArray1", "description": "A global variable holding an array of strings", "label" : "Global Variable String Array" "created" : "2008-11-18T15:25:22.535+00:00", "modified" : "2008-11-18T15:25:22.535+00:00", "lastModifiedBy" : "prasen", "type" : "stringArray", "value" : ["\"String1\"", "\"String2\"", "\"String3\""], "links": [{ "method": "GET", "rel": "self", "href": "http://<server>/SASDecisionServicesistration/ rest/variables/GVStringArray1", "uri": "variables/GVStringArray1",

454 Appendix 7 / SAS Decision Services istration "type": "application/vnd.sas.decision.variable" }, { "method": "GET", "rel": "value", "href": "http://<server>/SASDecisionServicesistration/ rest/variables/GVStringArray1/value", "uri": "variables/GVStringArray1/value", "type": "application/json" }, { "method": "PUT", "rel": "value", "href": "http://<server>/SASDecisionServicesistration/ rest/variables/GVStringArray1/value", "uri": "variables/GVStringArray1/value", "type": "application/json" }] }

application/vnd.sas.decision.batch.update.request The application/vnd.sas.decision.batch.update.request media type represents a command to update multiple objects in a collection, identified by the IDs in the selection field. This is used for activating or deactivating multiple decision flows and to set the time-out value for multiple decision definitions in the SAS Decision Services istration API. The application/vnd.sas.decision.batch.update.request media type contains the following . Name

Type

Description

version

integer


selection

array

An array of IDs of the objects that need to be updated. Note: In SAS Decision Services, all IDs are strings.

Media Types

455

Name

Type

Description

updates

array

An array of update instructions, as defined in the JSON patch format. An update instruction includes the following fields: op (string) For the purposes of this media type, only updates are ed, so the value of the op field is always replaced. No other values are ed. path (string) A string that specifies the path using / delimited parts. For the use cases ed in the SAS Decision Services istration API, the value of the path is the name of the field. value (any) The value that is to be assigned to the path. The type of the value is determined by the type of the field updated. For example, if an activation status is updated, the value of the path is active and value of value is true. ifUnmodifiedSince (dateTime) (Optional) This member contains the timestamp. If this value is present, the resource is updated only when the resource has not been modified since the supplied timestamp. If the resource has been modified, the change is not made, and the update is considered a failure and handled per the failurePolicy member. If this member is not present, the update is always applied. The first implementation of the istration API ignores the value of this member if it is present. Allowed values for the path and value are context dependent. This media

456 Appendix 7 / SAS Decision Services istration Name

Type

Description

failurePolicy

string

A string token that specifies how failures are handled. The allowed values are ignore and rollback. Using ignore continues to process other resources specified in the selection, even when the Update operation failed for some. Using rollback leaves the system in the original state without any updates. If an error is encountered while updating one of the resources specified in the selection field above.

Here is an example of application/vnd.sas.decision.batch.update.request: { "version" : 1, "selection" : [ "id1", "id2", ...., "idn" ], "updates" : [ { "op": "replace", "path": "/active", "value": true }, { "op": "replace", "path": "/timeOut", "value": 10 } ], "failurePolicy" : "ignore" }

application/vnd.sas.decision.batch.update.result The application/vnd.sas.decision.batch.update.result media type represents the result of a bulk update on a set of SAS Decision Services resources. Name

Type

Description

version

integer


startTimestamp

dateTime

The server timestamp indicating when the server started to process the request.

endTimestamp

dateTime

The server timestamp indicating when the server finished processing the request.

Media Types

457

Name

Type

Description

successCount

integer

Specifies how many resources were updated successfully as a result of the request. If the failure mode is set to rollback, then this value should either be 0 (meaning no updates), or the size of the selection array.

failureCount

integer

Specifies how many resources were not updated successfully as a result of the request. If the failure mode is set to rollback, then this value should either be 0 (meaning that all updates were successful), or the size of the selection array (meaning no updates).

results

array

An array of result objects. One per resource is specified in the selection field of the request. The result includes the following fields: id (string) The ID of the resource that was updated or not updated. status (string) The value of success or failure, indicating whether the resource was updated successfully or failed to update. error (object) (Optional) An error object. Included if the update failed and resulted in errors that can be linked to this particular resource.

error

object

(Optional) An error object. Included if the update failed.

links


One or more link objects.

{ "version" : 1, "startTimeStamp" : "time started",

458 Appendix 7 / SAS Decision Services istration "endTimeStamp" : "end time", "results" : [{ "id" : "id1", "status" : "success" },{ "id" : "id2", "status" : "failed", "error" : { "errorCode": 404, "httpStatusCode": 404, "details": [ "Decision Definition GetRecommendation was referenced by Decision Flow Recommendation Campaign, but was not found." ], "links": [], "message": "Activation failed.", "remediation": "Please ensure all relevant artifacts are available in the repository.", "version": 1 } }] "error" : { "errorCode": 409, "httpStatusCode": 409, "details": [ "Decision Definition GetRecommendation was referenced by Decision Flow Recommendation Campaign, but was not found." "Decision Definition GetRecommendation was referenced by Decision Flow Recommendation Campaign as well as Recommendation Campaign2. Only one Decision Flow can reference a Decision Definition." ], "links": [], "message": "Activation failed.", "version": 1 } }

Resources and Collections Resource / The / resource returns an object that contains a collection of links to the three top-level collections that are surfaced by this API: n /decisionDefinitions n /decisionFlows n /variables

The / resource uses the GET / method, which requires authentication, and has a request URL of GET http://www.example.com/ SASDecisionServicesistration/rest/. Here is an example of the JSON representation:

Resources and Collections

459

{ "links": [ { "href": "http://www.example.com/SASDecisionServicesistration/ rest/decisionDefinitions" "method": "GET", "rel": "decisionDefinitions", "type": "application/vnd.sas.collection", "uri": "/decisionDefinitions" }, { "href": "http://www.example.com/SASDecisionServicesistration/ rest/decisionFlows" "method": "GET", "rel": "decisionFlows", "type": "application/vnd.sas.collection", "uri": "/decisionFlows" }, { "href": "http://www.example.com/SASDecisionServicesistration/ rest/variables" "method": "GET", "rel": "variables", "type": "application/vnd.sas.collection", "uri": "/variables" } ] }

Here is an example of the JSON representation:

Here are the HTTP response codes: 200 OK 401 Unauthorized

460 Appendix 7 / SAS Decision Services istration 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET / returns the following media type representations by setting the Accept: header of the request: n application/json n application/xml

Collection /decisionDefinitions Overview The /decisionDefinitions represents the collection of decision definitions available in a run-time deployment. A decision definition is usually associated with one or more decision flows, only one of which can be active. The /decisionDefinitions collection has the following methods: n GET n POST

The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/decisionDefinitions. The GET method returns a collection of decision definition summaries corresponding to the decision definitions in the system. The collection s pagination and filtering by the label (display name) of the decision definition. The GET method has the following query parameters: Name

Type

Description

?start

integer

The starting index of the first item in a page. The index is 0-based. The default is 0.

?limit

integer

The maximum number of definition summaries to return in this page of results. The actual number of returned definition summaries can be less if the collection has been exhausted. The default is 10.


461

Name

Type

Description

?label

string

Filters by the label of the decision definition. The label is also known as the display name.

Here is an example of the JSON representation: {

"version" : 2, "start" : start, "limit" : limit, "count" : count, "name" : "decisionDefinitionSummaries", "accept": "application/vnd.sas.decision.definition.summary+json" "items" : [ { application/vnd.sas.decision.definition.summary+json contenti }, { application/vnd.sas.decision.definition.summary+json contenti+1 }, ... { application/vnd.sas.decision.definition.summary+json contentn }, ], "links: [ { "rel" : "first", "method" : "GET", ... }, { "rel" : "prev", "method" : "GET", ... }, { "rel" : "next", "method" : "GET", ... }, { "rel" : "last", "method" : "GET", ... }, ... ]

}

Here is an example of the JSON representation: <decisionDefinitionSummary> <decisionDefinitionSummary> ... <decisionDefinitionSummary>

462 Appendix 7 / SAS Decision Services istration Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representations by setting the Accept: header of the request: n application/vnd.sas.collection+json;version=2 n application/vnd.sas.collection+xml;version=2 n application/vnd.sas.collection+json n application/vnd.sas.collection+xml n application/json n application/xml

The POST method sets a time out for a group of decision definitions. Changing the artifacts in use by the engine is expensive and requires validating any new changes against the existing configuration and artifacts already loaded. Bulk update methods like these collect all the changes required and perform the validation only once instead of once per change. This allows for meeting strict performance requirements. The POST method requires authentication and has a request URL of POST http://www.example.com/SASDecisionServicesistration/rest/ decisionDefinitions. The POST method accepts the following content types, as named by the Content-Type: header: n application/vnd.sas.decision.batch.update.request+json n application/vnd.sas.decision.batch.update.request+xml n application/json n application/xml

Because only the time-out field can be updated, the updates array can contain only a single entry with the value of the op field set to replace, the value of the path field set to time out, and the value field set to a positive floating point number representing the time-out value in seconds. A response returns the results of the update as a application/ vnd.sas.decision.batch.update.result. Here are the HTTP response codes: 200 OK


463

400 Bad Request 401 Unauthorized 403 Forbidden 404 Not found. 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. The POST method can return the following media type representations by setting the Accept: header of the request: n application/vnd.sas.decision.batch.update.results+json n application/vnd.sas.decision.batch.update.results+xml n application/json n application/xml

Resource /decisionDefinitions/{decisionId} The /decisionDefinitions/{decisionId} resource represents a single decision definition in the system. The GET method has the following query parameters: Name

Type

Description

{decisionId}

string

The URL-encoded name of the decision definition.

The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/decisionDefinitions/ {decisionId} . The GET method returns a representation of a single decision definition summary as identified by the decisionId. Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden 404 Not found

464 Appendix 7 / SAS Decision Services istration 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representations by setting the Accept: header of the request: n application/vnd.sas.decision.definition.summary+json n application/vnd.sas.decision.definition.summary+xml n application/json n application/xml

Resource /decisionDefinitions/{decisionId}/timeout The /decisionDefinitions/{decisionId}/timeout resource represents the value of the timeout, in seconds, for this decision definition. This value is used to determine whether a decision flow execution has gone on for too long and should be stopped. The timeout value is described in the application/ vnd.sas.decision.definition.summary media type. The value is a positive floating point number and is returned or accepted as text/plain. Name

Type

Description

{decisionId}

string


The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/decisionDefinitions/ {decisionId}/timeout. The GET method returns the value of the timeout, in seconds, for the decision definition identified by the decisionId. Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representation by setting the Accept: header of the request:


465

n text/plain

The PUT method sets the value of the timeout, in seconds, for the decision definition identified by the decisionId. Note: For updating the timeout value for multiple decision definitions, the batch update process is the most efficient option. The PUT method requires authentication and has a request URL of PUT http:// www.example.com/SASDecisionServicesistration/rest/decisionDefinitions/ {decisionId}/timeout. The PUT method accepts the following content type, as named by the ContentType: header: n text/plain

Here are the HTTP response codes: 204 No content 400 Bad request 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes.

Resource /decisionDefinitions/{decisionId}/timeoutEnabled The /decisionDefinitions/{decisionId}/timeoutEnabled resource represents a Boolean value to indicate whether timeout processing is turned on for this decision definition, as identified by the decisionId. Name

Type

Description

{decisionId}

string


The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/decisionDefinitions/ {decisionId}/timeoutEnabled . The GET method returns the value of the timeoutEnabled flag for this decision definition. The value is returned as a Boolean value. Here are the HTTP response codes: 200 OK

466 Appendix 7 / SAS Decision Services istration 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representation by setting the Accept: header of the request: n text/plain

The PUT method updates the value of the timeoutEnabled flag for this decision definition. Accepted values are Boolean values. The PUT method requires authentication and has a request URL of PUT http:// www.example.com/SASDecisionServicesistration/rest/decisionDefinitions/ {decisionId}/timeoutEnabled. The PUT method accepts the following content type, as named by the ContentType: header: n text/plain


Collection /decisionFlows Overview The /decisionFlows collection represents the collection of decision flows in the system. Every decision flow is associated with a decision definition that it


467

references using the decisionId. It is possible that the referenced decision definition is not available in the system. In such cases, the decision flow is considered invalid. Decision flows can be active or inactive. Only valid decision flows can be active. Also, multiple decision flows can be associated with a decision definition. Only a single such flow can be active. The /decisionFlows collection has the following methods: n GET n POST

The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/decisionFlows. The GET method returns a collection of decision definition summaries corresponding to the decision definitions in the system. The collection s pagination and filtering by the following attributes: label (string) The display name of the decision flow. active (Boolean) The flag indicating whether the decision flow is active or not. decisionId (string) The ID of the decision definition that this flow is associated with. The GET method has the following query parameters: Name

Type

Description

?start

integer

The starting index of the first decision flow in a page. The index is 0based. The default is 0.

?limit

integer

The maximum number of decision flows to return in this page of results. The actual number of returned decision flows can be less, if the collection has been exhausted. The default is 10.

?label

string

Returns decision flows that have this display name.

?active

Boolean

Returns decision flows that are active or not based on the value of this attribute.

?decisionId

string

Returns decision flows that are associated with a decision definition with this ID. There could be more than one such decision flow.

Here is an example of the JSON representation: {

"version" : 2,

468 Appendix 7 / SAS Decision Services istration "start" : start, "limit" : limit, "count" : count, "name" : "decisionFlowSummaries", "accept": "application/vnd.sas.decision.flow.summary+json" "items" : [ { application/vnd.sas.decision.flow.summary+json contenti }, { application/vnd.sas.decision.flow.summary+json contenti+1 }, ... { application/vnd.sas.decision.flow.summary+json contentn }, ], "links: [ { "rel" : "first", "method" : "GET", ... }, { "rel" : "prev", "method" : "GET", ... }, { "rel" : "next", "method" : "GET", ... }, { "rel" : "last", "method" : "GET", ... }, ... ] }

Here is an example of the JSON representation: <decisionFlowSummary> <decisionFlowSummary> ... <decisionFlowSummary>

Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden


469

500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representations by setting the Accept: header of the request: n application/vnd.sas.collection+json;version=2 n application/vnd.sas.collection+xml;version=2 n application/vnd.sas.collection+json n application/vnd.sas.collection+xml n application/json n application/xml

The POST method activates or deactivates multiple flows in a batch. Changing artifacts in use by the engine is expensive and requires validating any new changes against the existing configuration and artifacts already loaded. Bulk update methods like these collect all the changes required and perform the validation only once instead of once per change. This allows for meeting strict performance requirements. The POST method requires authentication and has a request URL of POST http://www.example.com/SASDecisionServicesistration/rest/ decisionFlows. The POST method accepts the following content types, as named by the Content-Type: header: n application/vnd.sas.decision.batch.update.request+json n application/vnd.sas.decision.batch.update.request+xml n application/json n application/xml

Since only the active field can be updated, the updates array can contain only a single entry with the value of the op field set to replace, the value of the path field set to active, and the value field set to a Boolean value representing whether the flows are active or not. Here are the HTTP response codes: 200 OK 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not found.

470 Appendix 7 / SAS Decision Services istration 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. The POST method can return the following media type representations by setting the Accept: header of the request: n application/vnd.sas.decision.batch.update.results+json n application/vnd.sas.decision.batch.update.results+xml n application/json n application/xml

Resource /decisionFlows/{decisionFlowId} The /decisionFlows/{decisionFlowId} resource represents a single decision flow in the system as identified by the decisionFlowId. The GET method has the following query parameters: Name

Type

Description

{decisionFlowId}

string

The URL-encoded name of the decision flow.

The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/decisionFlows/ {decisionFlowId}. The GET method returns a single decision flow as identified by decisionFlowId. Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representations by setting the Accept: header of the request: n application/vnd.sas.decision.flow.summary+json n application/vnd.sas.decision.flow.summary+xml


471

n application/json n application/xml

Resource /decisionFlows/{decisionFlowId}/active The /decisionFlows/{decisionFlowId}/active resource represents the activation status of the decision flow identified by decisionFlowId. The GET method has the following query parameters: Name

Type

Description

{decisionFlowId}

string

The URL-encoded name of the decision flow.

The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/decisionFlows/ {decisionFlowId}/active. The GET method returns the activation status of this decision flow as a Boolean value. True if the decision flow is active, false otherwise. Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representations by setting the Accept: header of the request: n text/plain

The PUT method updates the value of the activation status of this decision flow. Accepted values are Boolean values. Note: For updating the activation status for multiple decision flows, the batch update process is the most efficient option. The PUT method requires authentication and has a request URL of PUT http:// www.example.com/SASDecisionServicesistration/rest/decisionFlows/ {decisionFlowId}/active. The PUT method accepts the following content type, as named by the ContentType: header: n text/plain

472 Appendix 7 / SAS Decision Services istration Here are the HTTP response codes: 204 No content 400 Bad request 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes.

Collection /variables Overview The /variables collection represents all of the variables in the system. The /variables collection has a GET method. The GET method requires authentication and has a request URL of GET http://www.example.com/ SASDecisionServicesistration/rest/variables. It returns a collection of resources that represents the variables in the system. The collection elements are instances of the application/ vnd.sas.decision.variable media type. The GET method has the following query parameters: Name

Type

Description

?start

integer

The starting index of the first variable in a page. The index is 0-based. The default is 0.

?limit

integer

The maximum number of variables to return in this page of results. The actual number of returned decision flows can be less, if the collection has been exhausted. The default is 10.

?label

string

Returns all variables that have this display name.

Here is an example of the JSON representation:

Resources and Collections {

"version" : 2, "start" : start, "limit" : limit, "count" : count, "name" : "variables", "accept": "application/vnd.sas.decision.variable+json" "items" : [ { application/vnd.sas.decision.variable+json contenti }, { application/vnd.sas.decision.variable+json contenti+1 }, ... { application/vnd.sas.decision.variable+json contentn }, ], "links: [ { "rel" : "first", "method" : "GET", ... }, { "rel" : "prev", "method" : "GET", ... }, { "rel" : "next", "method" : "GET", ... }, { "rel" : "last", "method" : "GET", ... }, ... ]

}

Here is an example of the JSON representation: ...

Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden

473

474 Appendix 7 / SAS Decision Services istration 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representations by setting the Accept: header of the request: n application/vnd.sas.collection+json;version=2 n application/vnd.sas.collection+xml;version=2 n application/vnd.sas.collection+json n application/vnd.sas.collection+xml n application/json n application/xml

Resource /variables/{variableId} The /variables/{variableId} resource represents a single variable in the system. The GET method has the following query parameters: Name

Type

Description

{variableId}

string

The URL-encoded name of the variable.

The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/variables/ {variableId}. The GET method returns a representation of a single variable as identified by the variableId. Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes.


475

GET returns the following media type representations by setting the Accept: header of the request: n application/vnd.sas.decision.variable+json n application/vnd.sas.decision.variable+xml n application/json n application/xml

Resource /variables/{variableId}/value The /variables/{variableId}/value resource represents the value of this variable identified by the variableId. Primitive values like string or Boolean are returned as text/plain. Complex values like array or table are returned as application/json or application/xml. Depending on the type of the variable, the allowed values can be parsed or set. The GET method has the following query parameters: Name

Type

Description

{variableId}

string

The URL-encoded name of the variable.

The GET method requires authentication and has a request URL of GET http:// www.example.com/SASDecisionServicesistration/rest/variables/ {variableId}/value. The GET method returns the value of this variable. Here are the HTTP response codes: 200 OK 401 Unauthorized 403 Forbidden 404 Not found 500 Server error Note: These are the most common HTTP response codes. You should be prepared to handle all valid HTTP response codes, including 3xx redirection response codes. GET returns the following media type representations by setting the Accept: header of the request: n text/plain n application/json n application/xml

The PUT method sets the value of this variable with the supplied value.

476 Appendix 7 / SAS Decision Services istration The PUT method requires authentication and has a request URL of PUT http:// www.example.com/SASDecisionServicesistration/rest/variables/ {variableId}/value. The PUT method accepts the following content type, as named by the ContentType: header: n text/plain n application/json n application/xml


477

Recommended Reading Here is the recommended reading list for this title: n SAS Real-Time Decision Manager: ’s Guide. n SAS Federation Server: ’s Guide n SAS Federation Server Manager: ’s Guide n SAS Federation Server Manager: 's Guide n SAS Intelligence Platform: Security istration Guide n SAS Intelligence Platform: Application Server istration Guide n SAS Intelligence Platform: Installation and Configuration Guide n SAS Intelligence Platform: Data istration Guide n SAS Intelligence Platform: Migration Guide n Base SAS Procedures Guide n SAS Stored Processes: Developer’s Guide n SAS Intelligence Platform Middle-Tier: ’s Guide n SAS BI Web Services: Developer’s Guide n SAS Customer Intelligence: Deployment Guide n SAS Visual Analytics: Installation and Configuration Guide n SAS Visual Analytics: istration Guide n SAS Visual Analytics: ’s Guide n SAS National Language (NLS): Reference Guide n SAS Marketing Automation and SAS Real-Time Decision Manager: Migration

Guide n SAS Decision Services: Configuration Guide n SAS Environment Manager: ’s Guide

For a complete list of SAS publications, go to sas.com/store/books. If you have questions about which titles you need, please a SAS Representative: SAS Books SAS Campus Drive Cary, NC 27513-2414 Phone: 1-800-727-0025 Fax: 1-919-677-4444 Email: [email protected] Web address: sas.com/store/books

478 Recommended Reading

479

Index Special Characters _EXT tables 351 $_Log_JDBCConnectionResourc e 120

A acceptance response type 356 access control template See ACT access permissions 106 business context 144 capabilities 94 groups 103 roles 94 SAS Customer Intelligence assets 219 SAS identities 93 Manager plug-in 105 s capabilities 94 permissions 106 roles 94 SAS identities 93 Manager plug-in 105 ACT 107 activating decision flows 243 activating flows 54 activities 57, 187 See also General I/O activities See also web service activities date and time formats 11 promotion rules 238 activity deploy to a remote environment 406 Add Channels utility 379 errors 380 istrative tasks 6 aliases, defining for schemas 127 Apache Commons Database Connection Pooling (DB) 286 application servers 50 arbitration processing large amounts of data 256

architecture deg 18 SAS Intelligence Platform 17 storage 21 archiving data 251 arrays, methods for 175 ASCII characters and translated data 372 attachments disabling 86 autoexec_mods.sas file and object spawner 47

B backing up campaigns 253 backing up data 251 batch simulation tables field length 88 BI web services 71, 162 Boolean data type 11 Boolean List data type 11 Boolean values in SAS activities 11 browsers Firefox 110 bulk-load facility and DB2 277 and Netezza 277 and Oracle 277 and SQL Server - ODBC connection 277 and SQL Server - OLE DB connection 277 and Teradata 277 enabling in business context 276 business contexts access permissions 144 and bulk-load facility 276 and common data model 342 creating 143 data grid library 227 data set options 276, 278 library location for common data model 373 permissions 107, 143 updating subjects 368

480 Index

C calculated items 13 campaign components create 152 design 152 test 152 campaign usage calculated items 13 data types 11 decision campaign flow 8 overview 7 variable mapping 11 campaigns and LOCKDOWN statement 92 backing up 252 deploying 237 exporting 381 importing 381 improving performance of 274 in common data model 344 listing input variables 405 marking for deployment 401 publishing to reporting library 401 releasing for editing 305 restoring 253 sample 89 undeploying 237 capabilities 94 and predefined roles 100 comments 99 customer intelligence studio istration resources 99 decision application resources 97, 98 decision nodes resources 98 decision operations 96 reports 99 cells in common data model 346 channels adding 379 Character data type 11 Character List data type 11 CI__HISTORY 353 CICommon web service 273 client tier 17 clustering best practices 256 command-line utilities 378 comments capabilities 99 common data model 339 _EXT tables 351 and DB2 366 and Greenplum 366 and multiple business contexts 342

and Netezza 366 and Oracle 366 and PostgreSQL 367 and SQL Server 367 and SQL Server - ODBC connection 367 and SQL Server - OLE DB connection 367 and Teradata 368 campaign tables 344 cell tables 346 changing location 373 communication tables 345 concurrent loading 273 configuring to display reports 195 control group tables 349 creating table structure 364 custom details 371 deploying 364 error codes 322 extension tables 370 history 63, 138 history tables 349, 352, 368 lookup tables 357 migrating tables 374 package tables 346 prepopulated values 357 presented treatment history table 357 publishing 373 response tables 349, 354 saving 373 treatment tables 346 UDF tables 352 updating 341 communications in common data model 345 concurrent updates 70 configuration 52 $_Log_JDBCConnectionResou rce 120 additional databases 129 additional Federation Servers for server cluster 254 for use of data sets 133, 293 GenerallO_Activity_Resource 120 SAS_Activity_Resource 119 connections, dropping idle 290 history tables concurrent loading 273 in common data model 349 setting up 368 Content Repositories folder 218 control groups in common data model 349 copying and pasting

Index

SAS Management Console folders 220 custom details in common data model 371 custom properties map level 151 Customer Intelligence Common group 104 Customer Intelligence group 104 Customer Intelligence Advanced Campaign Designer group 104 Customer Intelligence Basic Campaign Designer group 104 Customer Intelligence Common: role 96 customer intelligence studio istration resources capabilities 99 Customer Intelligence: istration role 96 Customer Intelligence: Advanced Campaign Design role 95 Customer Intelligence: Basic Campaign Design role 95 Customer Intelligence: Usage role 95

D data accessing 33 archiving 251 backing up 251, 253 restoring 253 Data Grid data type 11 data grids data libraries 227 data processes data libraries 227 data sets configuration for use 133, 293 data sources and data grids 227 multiple 34 ing 34 data tier 17 data type mappings 174 DS2 packages 174 web service activities 161 data types 11 Boolean 11 Boolean List 11 Character 11 Character List 11

481

Data Grid 11 Date 11 Date List 11 Double 11 Double List 11 Integer 11 Integer List 11 Database Connection Pooling (DB) 286 database I/O 29 database logs 327 database servers 50 databases improving performance 268 installing and configuring additional 130 requirements 129 date and time formats 11 Date data type 11 Date List data type 11 DB2 and bulk-load facility 277 and common data model 366 DB (Database Connection Pooling) 286 DBCS See double-byte character sets deactivating flows 54 decision application resources capabilities 97, 98 decision campaign life cycle 52 decision campaign flow 8 decision flows 60 activating 243 managing global variables 63, 89 promoting 222, 237 rules for promoting 238 sub-flows 60 decision nodes capabilities 98 decision operations capabilities 96 Decision Services Manager plug-in 218 decline response type 356 delimiters for multiple treatments 88 deploying campaigns 237 deployment istering 229 best practices for performance 24 database I/O considerations 29 easy button deployments 25 hardware capacity planning 27 production deployments 26 scenarios 28 deployment environment managing 230

482 Index development environment components 49, 50 installation 51 direct responses 355 Double data type 11 Double List data type 11 double-byte character sets in SAS Customer Intelligence tables 83 DS2 history processes 270 DS2 activities execute method 167 DS2 code parameter limitations 166 programming tips 187 test with SAS Federation Server 167 DS2 configuration settings SAS Decision Services 6.4 and SAS Federation Server 4.2 165 DS2 debugging configuring logging 331 DS2 package create 168 DS2 packages creating 168 data type mappings 174 in repository 54 sas_activity_tests (sample) package 181 tap_array package 175 tap_hash package 175 DS2 procedure 168 DS2 programming 165

E environment starting 250 environment variables 266 error codes common data model 322 errors Add Channels utility 380 SAS Metadata Server 30 SAVE BINDINGS FAILED 256 event variables data libraries 227 events 58 importing 247 promotion rules 238 time-out setting 84 exporting

best practices 223 campaigns 381 exports troubleshooting 48

F failover, hardware 22 Federation Servers See SAS Federation Servers Firefox browser Integrated Windows Authentication 110 flows See also decision flows activating and deactivating 54 folders Content Repositories 218 importing and exporting objects between 381 SAS Decision Services servers 218

G General I/O activities 65 Insert operation 66 Read operation 66 Update operation 66 GenerallO_Activity_Resource 120 global variables 63 and testing 63 managing 89 predefined 63 setting delimiters 64 Greenplum 33 and common data model 366 groups 103 istering 103 istering hip 105 Customer Intelligence 104 Customer Intelligence Advanced Campaign Designer 104 Customer Intelligence Basic Campaign Designer 104 Customer Intelligence Common 104 overview 103 permissions 106 Public 103 SAS s 104 SAS Decision Services Database s 104

Index

SAS Federation Server s 105 SAS System Services 104 SAS s 103 Manager plug-in 105

H halo response type 356 hardware capacity planning 27 hardware failover 22 hash objects 175 history activate a history process 270 in common data model 138, 349 history tables 352, 368 HTTP servers 50

483

third-party components 71 web application servers 71 Integer data type 11 Integer List data type 11 Integrated Windows Authentication Firefox browser 110 integration with SAS Model Manager 80 integration utilities See SAS Customer Intelligence Integration Utilities integration with customer channel through the client API for Java 159 with web services 153 integration with the customer channel through the REST API 158 with external web services 161

J I identifier importing 247 importing best practices 223 campaigns 381 memory size 227 reply definitions 247 response definitions 247 SAS packages 247 treatment campaign sets 246 inferred responses 355 information maps backing up 252 custom properties 151 understanding 145 input variables 405 generating reports 401 listing 401 inquiry response type 356 Insert operation (General I/O activities) 66 install setup instructions 83 installation best practices for performance 24 BI web services 71 choosing environments 51 database I/O considerations 29 deployment scenarios 28 easy button deployments 25 hardware capacity planning 27 production deployments 26 SAS Federation Server 72

Java 2 Enterprise Edition (J2EE) application servers 22, 51 JDBC connection resource create database domain 142 create database shared 142 JDBC Connection system resources 120, 229 creating 123 for General I/O activities 65 pool tuning for performance 286 JVM memory size 301 JVM options set 87

L Launcher errors 409 logs 407 libraries See SAS library resources library references (librefs) 35 defining 36 library resources 65, 127 defining schema aliases 127 Limit nodes troubleshooting 48 Lineage utility 394 lists separators 267 load balancing and SAS Stored Process Server 48

484 Index Load Treatments utility 385 locale and session encoding 372 LOCKDOWN statement and campaigns 92 locking errors 70 locks 305 logging configuring for DS2 debugging 330, 331 performance considerations 274 logs core 322 database 327 for troubleshooting 322 installation and configuration 327 SAS Customer Intelligence reporting client 323 SAS Customer Intelligence web client 323 SAS Decision Services Design Server 324 SAS Decision Services Engine Server 324 SAS Federation Server 325 SAS Metadata Server 327 SAS Stored Process Server 323 SAS Workspace Server 324 trace level 267 Windows event 327 lookup tables in common data model 357 prepopulating 372

M mark for deployment list of campaigns 229 Marketing Operations Management See SAS Marketing Operations Management marking campaigns for deployment from command line 401 hip istering groups 105 istering roles 105 metadata access to 103 backing up 252 methods arrays 175 validation 181 middle tier 17 models 80

importing 247 monitoring 88 multiple treatments set delimiters 88

N Netezza 33 and bulk-load facility 277 and common data model 366

O object spawner overview 47 object types See public object types offers 13 operating environments requirements 2 operational environment components 50 Oracle and bulk-load facility 277 and common data model 366 extension tables 370 table name restriction 370

P packages in common data model 346 s encoding 379 updated by SAS Deployment Manager 112 performance 273 See also system performance business context options 276, 278 data set options 276, 278 database 268 history processes 270 INSERTBUFF option 278 JVM memory size 301 loading history tables 273 permissions 106 ACT 107 business context 107, 143 capabilities 94 groups 103 manage in business context 144

Index

s 112 roles 94 SAS Customer Intelligence assets 219 SAS identities 93 SAS Management Console folders 218 SAS Marketing Operations Management 103 Manager plug-in 105 Platform Suite for SAS 20 PostgreSQL 33 and common data model 367 predefined roles capabilities 100 prepopulated values in common data model 357 process variables web service activities 161 production environment components 51 installation 51 servers 50 promotion activities 238 decision flows 222, 237 events 238 Public group 103 public object types 381 publishing campaigns 405

R Read operation (General I/O activities) 66 reference tables in common data model 357 prepopulating 372 ing data 34 reply definitions importing 247 reporting catalogs 138 reports displaying in Reports workspace 195 input variables 405 reports capabilities 99 Reports workspace displaying reports 195 repositories creating 56 deleting 56 removing unused objects 246, 399 viewing 54 response definitions

485

importing 247 response history tables concurrent loading 273 in common data model 349, 354 setting up 368 response types acceptance 356 decline 356 halo 356 inquiry 356 spill 356 responses direct 355 inferred 355 setting up history tables 368 restoring data 253 roles 94 istering 94 istering hip 105 creating 102 Customer Intelligence Common: 96 Customer Intelligence: istration 96 Customer Intelligence: Advanced Campaign Design 95 Customer Intelligence: Basic Campaign Design 95 Customer Intelligence: Usage 95 modifying 103 permissions 106 predefined 95 Manager plug-in 105 view in SAS Management Console 94 rows maximum number to display 266

S sample campaign 89 SAS 17 SAS activities Boolean values in 11 creating XML 174 SAS activity XML create 174 SAS s group 104 SAS Content Server backing up 253 SAS Customer Intelligence assets 219 backing up 253 logs 322

486 Index session timeout value 83 SAS Customer Intelligence Integration Utilities 253 SAS Customer Intelligence reporting client logs 323 SAS Customer Intelligence Services ID 93 SAS Customer Intelligence solution overview 2 SAS Customer Intelligence Studio creation of global variables 90 sessions 266 SAS Customer Intelligence web client logs 323 SAS data sets configuration for use 133, 293 SAS Decision Services and SAS Real-Time Decision Manager 6 concepts 22 configuration 52 Decision Services Manager plug-in 218 integration with SAS Model Manager 80 overview 6 viewing repositories 54 SAS Decision Services Database s group 104 SAS Decision Services Design Server 51 logs 324 SAS Decision Services engine 22 SAS Decision Services Engine servers 50, 51 SAS Decision Services Engine Server logs 324 SAS Decision Services repositories 54 SAS Decision Services servers folder 218 SAS Deployment Manager updated s 112 SAS Deployment Wizard 20 SAS DS2 packages out of the box 175 SAS Federation Server create database domain 140 create database shared 140 logs 325 SAS Federation Server s group 105 SAS Federation Servers 50, 51, 72, 138 allocating computing resources 120

configuring to form a server cluster 254 options for performance 274 requirements for databases 129 tuning considerations 290 SAS identities 93 SAS Intelligence Platform architecture 17 security istration 92 SAS library resources 35 SAS Management Console 51 copying and pasting folders 220 Decision Services Manager plug-in 218 Folders tab 218 SAS Marketing Operations Management access permissions 103 SAS Metadata Repository 51 SAS Metadata Server backing up 253 errors 30 log 327 SAS Metadata Servers 50 SAS Model Manager integration with SAS Decision Services 80 SAS packages importing and exporting 383 SAS Real-Time Decision Manager and SAS Decision Services 6 arbitration options 256 integration with other SAS products 79 integration with SAS Customer Intelligence solution 2 SAS Stored Process Server logs 323 SAS System Services group 104 SAS Technical 336 SAS s group 103 SAS Visual Analytics istration and Reporting 20 SAS Web Application Server 51 SAS Workspace Server logs 324 SAS_Activity_Resource 119 sas_activity_tests (sample) DS2 package 181 SAS/ACCESS 33 SASMSG function 372 sasv9.cfg and double-byte character sets 83 and object spawner 47 scalability 22 schema aliases, defining 127

Index 487

security 92 capabilities 94 groups 103 permissions 106 roles 94 SAS identities 93 SAS Intelligence Platform 92 Manager plug-in 105 self-learner run stored process 406 self-learner stored process executing from command line 401 separators 64, 267 servers application servers 50 clustering 22, 256 database servers 50 HTTP servers 50 Java 2 Enterprise Edition (J2EE) application servers 22, 51 naming during setup 83 problems connecting to 83 production environment 50 SAS Decision Services Design Server 51 SAS Decision Services Engine Servers 50, 51 SAS Federation Servers 50, 51 SAS Metadata Servers 50 session encoding and locale 372 session timeout value 83 sessions recovery options 266 setup instructions deployment 82 install 83 server name 83 session timeout value 83 spill response type 356 Split nodes troubleshooting 48 SQL Server and common data model 367 and multiple databases 34 SQL Server - ODBC connection and bulk-load facility 277 and common data model 367 and multiple databases 34 SQL Server - OLE DB connection and bulk-load facility 277 and common data model 367 Stage node enabling 86 stored processes 273 performance 273

system performance allocating computing resources 120 best practices 24, 274 connection and statement pool tuning 291 database I/O considerations 29 JDBC performance tuning 286 SAS Federation Server tuning 290 server options 274 system resources 65, 119 JDBC Connection 65, 120, 229 promotion rules 238 Web Service Connection 125, 162

T tables double-byte character sets 83 tap_array DS2 package 175 tap_hash DS2 package 175 technical See SAS Technical Teradata and bulk-load facility 277 and common data model 368 test cases executing from command line 401 global variables 63 test environment components 51 installation 51 Test environment components 50 third-party components installation 71 third-party software requirements 2 tier client 17 data 17 definition of 17 middle 17 SAS server 17 time-out values, setting 85 timeout item recovery options 266 timeout value 83 treatment campaign sets deploying 246 importing 246 publishing to reporting library 401 treatment history concurrent loading 273 in common data model 357 treatments

488 Index and LOCKDOWN statement 93 in common data model 346 releasing for editing 305 separators 267 staging 63, 86 tuning connection and statement pools 291

U UDF tables 352 Unicode and translated data 372 Update operation (General I/O activities) 66 IDs permissions 106 SAS identities 93 Manager plug-in 105 Manager plug-in 105 utilities Add Channels 379 export and import 381 lineage 394

V validation

methods for 181 variable mapping 11 variables, global See global variables

W web application servers installation 71 web service activities 161 BI web services 162 in repository 54 Web Service Connection system resources for 162 Web Service Connection system resources creating 125 for web service activities 162 web services and history processes 270 request example 154 WSDL (Web Service Definition Language) files 156

X XML creating for SAS activities 174

Rtdm Guide.pdf 44k3g

Overview 26281t

More details 6y5l6z

Related Documents 3h463d

Rtdm Guide.pdf 44k3g

4p345f

Law 653lp

Guide 2m5n4k

Pramuka 2d43n

Poa 47281d

More Documents from "temp" 26v6

Rtdm Guide.pdf 44k3g

Test Lektion 08 265g1h

Alessia Cara - How Far Ill Go -tabs 4u4l1w

Robin Winkler Clinic Psychological Services q27o

Etapas Del Aprendizaje Dr. Carlos Logatt Gabner 4a5h4r

Sap Gl Best Practice 1gu6m