Creating a Web Service Job

Problem

You want to create a job that can be executed by a Web service client. The job must be accessed across platforms, and the amount of data to be input and output is not large.

Solution

Create a Web service job, deploy it as a stored process, and then deploy the stored process as a Web service.

Your first task is to create a Web service job. The job must meet the requirements that are described in Requirements for Web Service Jobs. One way to meet these requirements is to create a job with a process flow similar to the flow in the following display.

Sample Process Flow for a Web Service Job

In the sample flow, INTABLE is a metadata object for an input table in XML format. Convert Temp GT is a generated transformation with custom SAS code that processes the input and produces a result. OUTTABLE is a metadata object for an output table in XML format. The small blue circle that overlays the table icons indicates that the input table and output table are configured as Web streams. Users with Web client software access the Web service job, and they are prompted to supply input. The job processes the input and displays the result to the Web client.

To create a Web service job, perform the following tasks:

It is assumed that the general prerequisites have been met, as described in Prerequisites for Web Service Jobs.

Tasks

Create the XML Inputs and Outputs for the Job

Perform the following steps to create the input and output tables for a Web service job. If you include test values in these tables, you might find it easier to test your job before it is deployed.

Use an XML editor to create an XML table for each input from the Web service client. Include test values in the input tables, if desired. Save each table to a separate file. For the sample job that is shown in Sample Process Flow for a Web Service Job, the physical name of the input table is InTemp.xml. The XML code for this table is as follows:
```
<TABLE>
   <INTABLE>
      <temperature> 40 </temperature>
      <Unit> C </Unit>
   </INTABLE>
</TABLE>
```
Use an XML editor to create an XML table for the output to the Web service client. Save that table to a file. For the sample job, the physical name of the output table is OutTemp.xml. The XML code for this table is as follows:
```
<TABLE>
   <OUTTABLE>
      <CalculatedTemperature> Temperature of 40 degrees Centigrade = 104 degrees Farenheit </CalculatedTemperature>
   </OUTTABLE>
</TABLE>
```

Create XML Libraries for the Inputs and Outputs

You must create a separate XML library for each input from the Web service client and each output from the job. SAS XML libraries differ from most SAS libraries in that the library metadata points to an XML file, not to a directory that contains XML files. The structure of your XML tables might require you to specify certain options in the library. For details about SAS XML libraries, see the SAS XML LIBNAME Engine: User's Guide.

Perform the following steps to create the libraries for the input and output tables in a Web service job:

On a file system that is accessible to the Web service client, create directories for the input and output tables. For the sample job, the physical path of the input directory is c:\public\input. The physical path of the output directory is c:\public\output.
Copy the input and output files that you created to the directories that you created. For the sample job, the physical path of the input file is c:\public\input\InTemp.xml. The physical path of the output file is c:\public\output\OutTemp.xml.
In SAS Data Integration Studio, to register a library for an input table in XML format, right-click a destination folder in the Folders tree. Then select NewLibrary from the pop-up menu.
In the New Library wizard, select SAS XML Library and click Next.
Use the pages of the wizard to specify values that are appropriate for the library for the input table. For the sample job, you can enter the following values:

Name: Intemp

Selected Server: SASApp

Libref: intemp

Engine: XML

XML File: c:\public\input\InTemp.xml

XML Type: Generic

Library Access: Blank
Repeat steps 1 through 5 for the output library. Use the pages of the wizard to specify values that are appropriate for that library. For the sample job, you can enter the following values:

Name: Outtemp

Selected Server: SASApp

Libref: outtemp

Engine: XML

XML File: c:\public\output\OutTemp.xml

XML Type: Generic

Library Access: Blank

Register the XML Inputs and Outputs

Perform the following steps to register the input and output tables for a Web service job:

Right-click the input library and click Register Tables in the pop-up menu.
Register the input table. For the sample job, the input table is InTemp.xml. For more information, see Register a Table with the Register Tables Wizard.
Right-click the output library and click Register Tables in the pop-up menu.
Register the output table. For the sample job, the output table is OutTemp.xml.

Create a Generated Transformation That Produces the Desired Output

You can use the Transformation Generator wizard to create a custom transformation that reads input in the form of an XML table, process the input, and then write output in the form of an XML table. For an introduction to the Transformation Generator wizard, see Creating and Using a Generated Transformation.

In the sample job, we need a custom transformation that reads values for temperature and scale, in the format specified by InTemp.xml. The transformation converts the temperature in one scale to the equivalent temperature in the other scale, and then writes the result in the format specified by OutTemp.xml.

Perform the following steps or similar steps to create a custom transformation for a job that can be deployed as a Web service:

Right-click the destination folder in the Folders tree where the new transformation should be stored. Then select NewTransformation. The first page of the Transformation Generator wizard displays.
Enter a name for the transformation. In the sample job, the transformation is named Convert Temp GT.
Review other values on this page and make changes as desired, and then click Next. The SAS Code page displays.

Add SAS code that reads input in the form of an XML table, process the input, and then write output in the form of an XML table. In the sample job, the following SAS code is added to this page.

data &_OUTPUT;
set &_INPUT;
keep CalculatedTemperature;
length NewTemperature 8.;
if (Unit="F") then
  do;
     NewTemperature=(5/9)*(Temperature-32);
    Unit="C";
    CalculatedTemperature = "Temperature of " || compress(temperature) ||
       " degrees Farenheit = "  || compress(NewTemperature) || 
       " degrees Centigrade" ;
  end;
else if (Unit="C") then
  do;
     NewTemperature=(9/5)*(Temperature)+32;
    Unit="F";
    CalculatedTemperature = "Temperature of " || compress(temperature) || 
      " degrees Centigrade = " || compress(NewTemperature) || 
      " degrees Farenheit" ;
  end;
else
  do;
     CalculatedTemperature="Temperature of " || compress(temperature) || 
        " with unit of " || compress(unit) || " cannot be converted ";
    Unit="";
  end;
run;

When you are satisfied with the code, click Next . The Options page displays. Specify options as desired. The sample job does not require any options. When ready, click Next. The Transform properties page displays.
Specify transformation properties as desired. For the sample job, the following properties are specified:

Transform supports inputs (selected)

Maximum number of inputs (1)

Transform supports outputs (selected)

Maximum number of outputs (1)

Automatically generate delete code for outputs (deselected)

Note: Be sure to deselect the Automatically generate delete code for outputs property. It is not appropriate for Web service jobs.
Click Finish to save the transformation. In the Folders tree, the custom transformation appears in the folder that you right-clicked in step 1. In the Transformations tree, the custom transformation appears in the Ungrouped folder or another category that you specified in step 3.

Create the Job

Perform the following steps to create the process flow for a job that can be deployed as a Web service:

Right-click the destination folder in the Folders tree where the new job should be stored. Then select NewJob. The New Jobs wizard displays.
Enter a name for the job. The sample job is named Convert Temp Job. Click OK. An empty job opens in the Job Editor.
Drag your custom transformation from a tree view into the job.
Drag an XML input table from a tree view into the job. Connect the input to the custom transformation. Repeat for as many inputs as you have.
Right-click the temporary output table for the transformation and select Replace. Select the XML output table.

Note: At this point, you should have a complete process flow. The process flow for the sample job looks similar to the process flow shown in the Sample Process Flow for a Web Service Job display.
If the metadata for each client input table points to an XML table with test values, you can test the job in SAS Data Integration Studio. Run the job and note the status messages. You can right-click the output table and select Open to verify that the values in the client output table are correct. If not, troubleshoot and correct the job.

Note: After the job is deployed, and the Web client executes the job, any physical table specified in the metadata for a Web stream input or output is ignored, and data submitted by the client is used instead.
Configure the client input and output as Web streams. Right-click a client input in the process flow and then select Web Stream from the pop-up menu. Repeat for all inputs and the output in the job. The Web stream icon, a small blue circle, should overlay the table icons for all tables in the job.
Save and close the job.