Using Faults in a Web Service Operation Mapping

Size: px

Start display at page:

Download "Using Faults in a Web Service Operation Mapping"

Silvia Evans
5 years ago
Views:

1 Using Faults in a Web Service Operation Mapping 2011 Informatica

2 Abstract You can configure a web service operation mapping with multiple Fault transformations in Informatica Developer. Each Fault transformation returns error messages to the web service client. This article describes the steps to create the Fault transformations, configure the SOAP messages in each transformation, and connect the transformations in the web service mapping. Supported Versions Data Services Table of Contents Overview Scenario Configuration Tasks Step 1. Import a WSDL Data Object Step 2. Create the Flat File Lookup Source Step 3. Create the Web Service Step 4. Configure the Input Transformation Step 5. Configure the Output Transformation Step 6. Configure the Fault Transformations Step 7. Configure a Router Transformation to Check Customer ID Step 8. Configure an Expression Transformation Step 9. Configure the Lookup Transformation Step 10. Configure a Router Transformation to Check Lookup Results Step 11. Configure an Expression Transformation for Customer Not Found Error Step 12. Test the Mapping Step 13. Deploy the Web Service Overview When you configure a web service, you define a mapping and the transformations that perform the web service operation in Informatica Developer. When the web service runs successfully, the web service returns data to the user from the Output transformation. When an error occurs, the web service returns a fault to the web service client. A web service generates the following types of faults: User-defined. Error messages that the Data Integration Service generates based on a condition in the mapping. Configure a Fault transformation to return user-defined messages to a web service client. The Fault transformation can pass hierarchical groups of data to a web service client in a SOAP message. Generic. Error messages that the Data Integration Service generates when it encounters system errors. You do not have to configure a Fault transformation for these messages. 2

When you create a user-defined fault, the fault message has the following default elements: Port FaultCode FaultString FaultActor Description A code that identifies the error message.

3 When you create a user-defined fault, the fault message has the following default elements: Port FaultCode FaultString FaultActor Description A code that identifies the error message. The error message text. A URI that identifies the source of the fault. The faultcode, faultstring, and faultactor nodes are standard elements in a fault. The faultactor element is optional. When you need to return more information to the user than the default elements, you can add elements to the fault message. The Developer tool creates a detail element in the fault message and adds elements and keys to the detail group. You can return multiple-occurring data in a hierarchical structure in the detail element. The detail element has the following structure: detail Key_detail FKey_To_Fault_Group FaultNameGroup Key_FaultName_Group FKey_detail Element_A Element_B Element_C Scenario Hypostores customer service representatives want to access customer credit ratings over a network. The customer service representatives need to view the current customer rating by customer ID. When the customer ID is not valid, the customer representative needs to receive a message that indicates that the customer ID is not found. Create a web service that receives a customer ID from the client and returns the customer credit rating from a lookup source. Create two web service faults that return error messages to the client when the customer is not found. The following figure shows the web service mapping: The web service contains the following transformations: Input transformation Receives the SOAP request that contains a customerid. 3

4 R_Numeric_Check A Router transformation that checks if the customerid is numeric. If the customerid is numeric, the Router transformation passes the customerid to a Lookup transformation. If the customerid is not numeric, the transformation passes the ID to an Expression transformation that generates error messages. Lookup_Customer A Lookup transformation that looks up the customerid in a flat file lookup source. The Lookup transformation returns the customer name and the credit rating. R_Check_Null_Results A Router transformation that checks for null values in the lookup results. If the lookup succeeds, the Router transformation returns the customer ID, customer name, and credit rating to the Output transformation. If the lookup fails, the Router transformation passes the customer ID to an Expression transformation that generates error messages. Output transformation Generates a SOAP response message that contains the customer ID, customer name, and credit rating. Exp_Cust_Not_Found_Msgs Expression transformation that generates error messages when the customer lookup fails. EXP_Cust_Not_Valid_Msgs Expression transformation that generates error messages when a customer ID is not numeric. Customer_Not_Found fault Fault transformation that returns a fault to the web service client when a customer is not found. Customer_Not_Valid fault Fault transformation that returns a fault to the web service client when the customerid is not numeric. Configuration Tasks To implement this scenario, you must have a WSDL that describes the web service you are going to connect to. Create the web service from a WSDL data object. 1. In the Developer tool, import a WSDL data object in the Model repository. The WSDL to defines the web service. 2. Create a flat file lookup source that contains the customer credit ratings. 3. Create the web service from the WSDL. 4. Configure the Input transformation by mapping nodes from the Operation input to output ports. 5. Configure the Output transformation by defining ports and mapping them to the Operation output hierarchy. 6. Configure the Fault transformations by creating ports and mapping them to each fault message hierarchy. 7. Create a Router transformation that checks for a numeric customer ID and routs an alphanumeric customer ID to an Expression transformation. 8. Create an Expression transformation that returns two error messages to the Fault transformation when the customer ID is not numeric. 9. Create the Lookup transformation. 10. Create a Router transformation that checks for null lookup results from the Lookup transformation. 11. Create an Expression transformation that returns two messages to the Fault transformation when null values occur. 12. Test the web service. 13. Deploy the web service to a Data Integration Service. 4

5 Step 1. Import a WSDL Data Object Before you create the web service, import a WSDL data object that describes the web service to create. The WSDL describes the SOAP request message and the SOAP response message between the web service and the web service client. It also describes the faults that the web service might return. Import the Get_Credit_Rating.wsdl file to create the data object in the Model repository. The following zip file contains a WSDL that you can import to the Model repository: Step 2. Create the Flat File Lookup Source Create a flat file data object to use as a lookup source. Each flat file record contains a customer number, the customer name, and the credit rating. For this example, the flat file name is Customer_Credit_Ratings.txt. The following zip file contains a Customer_Credit_Ratings.txt file that you can import to the Model repository: The file contains the following fields: Field Name Type Scale CCustomerID string 10 CCustName string 22 CCreditRating decimal 3 The file contains the following records with the fields delimited by commas: CCustomerID,CCustName,CCreditRating ,Josephthal Lyon & Ross, ,NRCA, ,Pond Equities, ,Schroder & Company, ,Yuasa Trading Company,800 When you import the flat file data object, replace the default field names with CCustomerID, CCustName, and CCreditRating. Place a copy of the flat file in a shared directory that the Data Integration Service can access. Configure the source file directory in the run-time properties of the flat file data object. Step 3. Create the Web Service Create a web service from a WSDL data object. 1. Create a web service from the Get_Credit_Rating WSDL data object. The WSDL describes an operation called Operation. 2. Select the Operation operation and click OK. 3. The wizard creates the following transformations: Transformation Type Description Input Input Receives the SOAP request and parses the XML message into groups of relational data. 5

6 Transformation Type Description Output Output Creates a SOAP response message to return to the web service client. Customer_Not_Valid Fault Generates user-defined error messages when the customer ID is not valid. Customer_Not_Found Fault Generates user-defined error messages when the customer is not found. Step 4. Configure the Input Transformation 1. Click the Input transformation in the editor. 2. Click the Ports view on the Properties tab. The following view appears: By default, the Extract the first level of the hierarchy option is enabled. The Developer tool creates the Operation input group and customerid port. 3. Verify the default configuration. The customerid node in the SOAP request is mapped to a customerid port. Step 5. Configure the Output Transformation 1. Click the Output transformation in the editor. 2. Click the Ports view on the Properties tab. The following view appears: 6

The Developer tool creates the Operation Response input group of ports. The group contains the customerid, custname, and credit_rating ports. 3. Verify the default configuration. Step 6.

7 The Developer tool creates the Operation Response input group of ports. The group contains the customerid, custname, and credit_rating ports. 3. Verify the default configuration. Step 6. Configure the Fault Transformations Configure the Fault transformations to generate the user-defined error messages from the web service operation. 1. Click the Customer_Not_Valid Fault transformation in the editor. 2. Click the Ports view on the Properties tab and choose Fault mapping. The Developer tool creates the faultcode, faultstring, and faultactor input ports in the transformation by default. For this example, the WSDL includes additional elements in the detail element of the fault hierarchy. The elements are Fault_Code and Fault_Msg. The Developer tool does not create ports for these elements. 3. Add the following input ports: Key Key value that you can map to keys in the fault and detail groups of the Operation fault. You must have a key value in order to create relationships between the groups. You can map the same input key value to each key in the Operation fault. Custom_Error_Code Error code for the additional message to return to the web service client when the customer is not valid. Custom_Error_Message Additional error message to return to the web service client when the customer is not valid. 7

4. Map the ports to the associated nodes in the Operation fault. Map the key port to each key in the Operation fault. 5. Click the Customer_Not_Found Fault transformation in the editor. 6.

For this example, the WSDL includes additional elements in the detail element of the fault hierarchy. The elements are Fault_Code and Fault_Msg. 7.

8 4. Map the ports to the associated nodes in the Operation fault. Map the key port to each key in the Operation fault. 5. Click the Customer_Not_Found Fault transformation in the editor. 6. Click the Ports view on the Properties tab and choose Fault mapping. The Developer tool creates the faultcode, faultstring, and faultactor input ports in the transformation. For this example, the WSDL includes additional elements in the detail element of the fault hierarchy. The elements are Fault_Code and Fault_Msg. 7. Add the following input ports: Key Key value that you can map to keys in the fault and detail groups of the Operation fault. You must have a key value in order to create relationships between the groups. You can map the same input key value to each key in the Operation fault. Custom_Error_Code Error code for the additional message to return to the web service client when the customer is not found. Custom_Error_Message Additional error message to return to the web service client when the customer is not found. 8. Map the ports to the appropriate nodes in the Fault operation. Map the key port to each key in the Operation fault. 8

Create a Router transformation named R_Numeric_Check. 2. Create one string input port for Customer. 3. On the Groups tab, create a group called Not_Valid. 4.

9 Step 7. Configure a Router Transformation to Check Customer ID Configure a Router transformation to check if the customerid is numeric. When the customer ID is not numeric, pass the customer ID to an Expression transformation that creates two error messages. Otherwise, pass the customer ID to the Lookup transformation. 1. Create a Router transformation named R_Numeric_Check. 2. Create one string input port for Customer. 3. On the Groups tab, create a group called Not_Valid. 4. Add the following group filter condition for the Not_Valid group: IS_NUMBER(Customer) = False The Router transformation has a Default output group and a Not_Valid output group. Each group has a Customer port. When Customer is not numeric, the Router transformation returns Customer to the Not_Valid group. Otherwise the transformation returns Customer to the Default group. 5. Connect the customerid port in the Input transformation to the Customer input port in R_Numeric_Check. Step 8. Configure an Expression Transformation to Generate an Error Message Configure an Expression transformation to return error message codes and messages when the customer ID is not numeric. The Expression transformation passes the message data to a Fault transformation. 1. Create an Expression transformation named Exp_Cust_Not_Valid_Msgs. 2. Create a string input port for CustomerID. 9

10 3. Create the following output ports: Name Type Precision Scale Expression Error_Code String 10 0 'ERR_1234' Error_Msg String 50 0 'Error retrieving credit rating for customer ' CustomerID '.' Det_Error_Code String 10 0 'ERR_5678' Det_Error_Msg String 50 0 'Customer number is not numeric.' PK bigint Create the PK port to use as a key in the Fault transformation. 4. Link the Customer output port from the Not_Valid group of R_Numeric_Check to the CustomerID input port of the Exp_Cust_Not_Numeric_Msgs transformation. 5. Link the output ports of the Exp_Cust_Not_Numeric_Msgs transformation to the Customer_Not_Valid Fault transformation. Link the Error_Code and Error_Message ports to the faultcode and faultstring ports. Do not link a port to the faultactor. Link the Det_Error_Code and the Det_Error_Message ports to the Custom_Error_Code and Custom_Error_Message ports. Link the PK port to Key port in the Customer_Not_Valid Fault transformation. Step 9. Configure the Lookup Transformation Configure a Lookup transformation that returns the customer name and credit rating from the Customer_Credit_Ratings.txt lookup source. The Lookup transformation returns null values when the lookup fails. 1. Create a flat file data object Lookup transformation. 2. In the New Lookup Transformation dialog box, browse for the Customer_Credit_Ratings flat file data object. 3. On multiple matches, return the first row. The Columns view shows the following columns in the flat file data object: Name Type Precision Return CCustomerID string 10 CCustname string 22 CCreditRating decimal 3 x 4. In the Overview view of the Properties tab, add the CustomerID port. Enable the port for output. 5. In the Lookup view, enter the following lookup condition: CCustomerID = CustomerID 6. Save the Lookup transformation and add the transformation to the web service mapping. 7. In the Lookup transformation Run-time view, verify that the Customer_Credit_Ratings.txt source file has a valid directory location. 10

Configure a Router Transformation to Check Lookup Results Configure a Router transformation that checks if the lookup results contain null values.

11 The directory must be accessible by the Data Integration Service. 8. Link the Customer port from the Default group in the R_Numeric_Check transformation to the CustomerID port of the Lookup transformation. Step 10. Configure a Router Transformation to Check Lookup Results Configure a Router transformation that checks if the lookup results contain null values. If the Lookup transformation returns customer information, the Router transformation passes the customer data to the Output transformation. If the Lookup transformation returns null values, the Router transformation returns the customerid and null values to an Expression transformation. 1. Create a Router transformation named R_Check_Null_Results. 2. Create the following input ports: Name Type Precision CustomerID string 10 CustName string 25 CreditRating integer On the Groups tab, create a group called Not_Found. 4. Add the following group filter condition for the Not_Valid group: ISNULL(CustomerID) The Router transformation has a Default output group and a Not_Found output group. Each group returns the CustomerID, CustName, and CreditRating. 11

12 When Customer is not found in the lookup, the Router transformation returns customer data to the Not_Found group. Otherwise the transformation returns customer data to the Default group. 5. Link the output ports from the Lookup transformation to the Router transformation CustomerID, CustName, and CreditRating input ports. 6. Link the Default ports of the Router transformation to the corresponding input ports in the Output transformation. Step 11. Configure an Expression Transformation for Customer Not Found Errors Configure an Expression transformation to return error messages that indicate that the customer was not found. The Expression transformation returns error codes and messages to the Fault transformation. 1. Create an Expression transformation named Exp_Cust_Not_Found_Msgs. 2. Create a string input port for CustomerID. 3. Create the following output ports: Name Type Precision Scale Expression Error_Code string 10 0 'XX_9999' Error_Msg string 50 0 'Operation failed.' Det_Error_Code string 10 0 'ZZ_1000' Det_Error_Msg string 50 0 'Customer not found.' CustomerKey bigint 19 0 TO_BIGINT(CustomerID) 4. Link the CustomerID from the Not_Found group of the R_Check_Null_Results transformation to the CustomerID port of the Exp_Cust_Not_Found_Msgs transformation. 5. Link the output ports from the R_Check_Null_Results transformation to the input ports of the Customer_Not_Found Fault transformation. Link the CustomerKey output port to the Key in the Customer_Not_Found Fault transformation. Step 12. Test the Mapping Test the web service mapping in the Developer tool. 1. Click Data Viewer view. 2. In the Input operation, replace the question mark (?) with a customer number that is valid in the flat file source, such as

3. Click Run. The Data Integration Service returns the following output: 4. In the Input operation, change the customer ID to 10110000 and click Run.

13 3. Click Run. The Data Integration Service returns the following output: 4. In the Input operation, change the customer ID to and click Run. The customer ID is a valid format, but the customer is not in the Customer_Credit_Ratings lookup file. The Data Integration Service returns the following output in Customer_Not_Found fault: 13

14 5. In the Input operation, change the customer ID to AA and click Run. The customer ID is not numeric. The Data Integration Service returns the following error messages from the Customer_Not_Valid fault: Step 13. Deploy the Web Service Deploy the web service to a Data Integration Service. 1. In the Developer tool, right-click the web service in the Object Explorer View. 2. Select Deploy. 3. In the Deploy to Services dialog box, browse for a Domain and select the Data Integration Services to deploy the web service to. 4. Choose to create an application. The wizard deploys the application to the Data Integration Services that you choose. You can view the web service in the Administrator tool. The Administrator tool also shows the web service WSDL URL in the web service general properties. The URL has a syntax similar to the following URL: Credit_Rating_Web_Service/. 5. To view a WSDL for the web service, enter the WSDL URL in a browser. You can copy the WSDL from the browser to a text editor and save the text as a file. Developers can use the WSDL file to create client applications that access the service. The WSDL soap address element contains the web service URL that the web service client must use to access the web service. Author Ellen Chandler Principal Technical Writer 14

Creating a Web Service that Accesses Data from Two Data Objects

Creating a Web Service that Accesses Data from Two Data Objects Informatica Abstract You can create a web service to provide web service clients access to data integration functionality. This article describes