Using Attachments with Web Services

Streaming attachments can be defined in metadata as data sources (input attachments) and data targets (output attachments). Three types of streaming attachments are available:

XML stream

specifies an attachment that is in-lined in the payload of the request or response as XML. You can also specify a schema for this data. The XML LIBNAME engine can generate schemas, and you can use the XML Mapper to map existing schema to the data. See the SAS XML LIBNAME Engine: User's Guide for more information. The schema is included in the generated WSDL for SOAP endpoints.

Note: You can specify single streaming output the same way you do with the XMLA Web service by selecting Stream as the result capability. However, using data targets provides more flexibility because you can provide the name of the attachment as well as provide a schema that matches your expected data.

generic stream

specifies an out-of-band binary attachment that is included with the request or response in one of the following ways:

If the attachment data is small, it can be included directly in the payload and encoded as Base64 binary data. This is the only means available for supplying attachments when using the plain XML message format.
If the attachment data is not small, then it is included out-of-band from the payload as a MIME multi-part related attachment where it is referenced from the payload via MTOM XOP/Include or SOAP with Attachments references (swaRef) when using the SOAP message format. When using RESTful access to BI Web Services, individual data output streams can be retrieved as stand-alone resources. For more information, see Supported Types of Input and Output for XML and JSON Messages.

Note: With MTOM attachments, you can set the AttachmentOptimizedThreshold configuration setting to control when generic streams are Base64 encoded or optimized as XOP/Include attachments.

data table

specifies that the input or output represents tabular data that is consumed in your SAS program by a LIBNAME engine.

Data tables are a new feature in SAS 9.3 Stored Processes. They can remove the need to write LIBNAME statements in your stored process code and enable that code to be more flexible and reusable. You can specify a template table in the stored process data table definition. A template table points to a table that is registered in metadata. When a stored process has a template for a source data table, that table's structure is examined in order to generate very specific input schema automatically for the SOAP endpoint's WSDL file. The generated schema describes precisely what columns clients need to supply for each row of input data in a <ClientTable> element. Clients can choose to supply a LIBNAME and MEMBERNAME pair in a <ServerTable> element for a source data table. The stored process engine then automatically assigns this LIBNAME for you.

Target data tables are very similar to source data tables but they return tabular data to the client. If you specify that a target data table is a <ServerTable> when invoking a Web service, then the output that is sent to that target in your SAS code is automatically stored in the LIBNAME and MEMBERNAME that you specify in the <ServerTable> element. If you specify that a target data table is a <ClientTable> when invoking a Web service, then the output that is sent to that target in your SAS code is sent back to the Web service client. Also, if you specify a template for a target data table, then the generated schema for that Web service precisely describes the structure of the tabular output XML returned from the Web service in a <ClientTable>. If you use a template with a target data table and specify that the output is a <ServerTable> when invoking the service, then the output that is sent to that target in your SAS code is automatically written to the specified template table. See the SAS Stored Processes: Developer's Guide for more information about writing SAS programs that use data tables.

The following code is an example of a schema definition for a Web service that expects one generic (binary) stream as an output response:

<element name="stpAllParm1Response">
   <complexType>
      <sequence>
         <element name="stpAllParm1Result">
            <complexType>
               <sequence>
                  <element maxOccurs="1" minOccurs="0" name="Streams">
                     <complexType>
                        <sequence>
                           <element maxOccurs="1" minOccurs="0" name="myAttachment">
                              <complexType>
                                 <sequence>
                                    <element name="Value" type="base64Binary"/>
                                 </sequence>
                                 <attribute name="contentType" type="string"/>
                              </complexType>
                           </element>
                        </sequence>
                     </complexType>
                  </element>
               </sequence>
             </complexType>
         </element>
      </sequence>
   </complexType>
</element>

In this generated schema, myAttachment is the name of the element that represents the output attachment. This name is defined by the user in metadata. This element is a container for the actual value of that attachment. The content type of the attachment can be returned as an attribute to further clarify the content of the data within the attachment.

Package type output is also supported. This type of output produces one or more attachments and packages them together as a single entity. To enable this type of output, select Package as the result capability for the stored process. The SAS code needs to produce packages to take advantage of this feature. There are several ways to produce packages in SAS code, including ODS and the Publishing Framework. See the SAS Stored Processes: Developer's Guide for more information about using packages in your stored processes.

Attachment definitions in metadata provide a means to establish a contract between all parties involved in a Web service request. SAS BI Web Services generates a WSDL and schema based on metadata definitions that provide a contract between the client and Web service. The Web service enforces that all required attachments are sent in the request. The SAS code that executes on the SAS server must be written in accordance to the metadata definitions that it is representing. Otherwise, problems might occur (for example, not reading the correct stream) resulting in SAS errors. If a SAS error occurs, the Web service returns a SOAP fault to the client when using SOAP endpoints or an HTTP error when using plain XML or JSON in RESTful invocations.