How To Create Soap Webservices In Java

Release Information

About...
Release Notes

New and Enhanced Features for InterSystems IRIS 2021.1
General Upgrade Information
Upgrade Compatibility Checklist for InterSystems IRIS 2021.1
Known Issues and Notes
Deprecated and Discontinued Features
Licensing and Use of InterSystems Web Server

Supported Platforms

Supported Technologies
Supported Languages
Discontinued Platforms and Technologies
Supported Version Interoperability
Cross-Product Technology Matrix

First Looks
Downloading Samples
Searching the Documentation

Deployment

About...
Containers

About...
First Look
Try a Community Edition Container
Running in Containers
InterSystems Cloud Manager

About...
InterSystems Cloud Manager
InterSystems Cloud Manager Guide

ICM Overview
Essential InterSystems Cloud Manager Elements
Using InterSystems Cloud Manager
ICM Reference
Containerless Deployment
Sharing ICM Deployments
Scripting with ICM
Using ICM with Custom and Third-Party Containers
Deploying on a Preexisting Cluster

InterSystems Kubernetes Operator

About...
Using the InterSystems Kubernetes Operator

Installation Kit

About...
Installation Basics
Installation Guide

Preparing to Install InterSystems IRIS
Installing InterSystems IRIS on Microsoft Windows
Installing InterSystems IRIS on UNIX®, Linux, and macOS
Upgrading InterSystems IRIS
Creating and Using an Installation Manifest
Adding UNIX® Installation Packages to an InterSystems IRIS Distribution

Configuration

About...
Automating Configuration
Configuration Parameters

Introduction to the Configuration Parameter File
[Actions]
[ComPorts]
[config]
[ConfigFile]
[Databases]
[Debug]
[Devices]
[DeviceSubTypes]
[ECP]
[ECPServers]
[Gateways]
[IO]
[Journal]
[LicenseServers]
[Map]
[MapMirrors]
[MirrorMember]
[Mirrors]
[Miscellaneous]
[Monitor]
[Namespaces]
[SQL]
[SqlSysDatatypes]
[SqlUserDatatypes]
[Startup]
[Telnet]

Data Migration

About...
Server Migration
ISQL Migration Guide

Overview

Transact-SQL (TSQL) Migration Guide

Planning and Performing TSQL Migration
InterSystems TSQL Constructs
InterSystems TSQL Language Elements
TSQL Commands
TSQL Settings
TSQL Functions
TSQL Variables
TSQL System Stored Procedures

DataMove

Adding Compiled Code

Administration

About...
System Administration

Using the Management Portal
Configuring InterSystems IRIS
Managing InterSystems IRIS
Managing InterSystems IRIS Licensing
Using InterSystems IRIS on Windows
Using InterSystems IRIS on UNIX®, Linux, and macOS
Connecting to Remote Servers
Using Multiple Instances of InterSystems IRIS
Configuring Third-Party Software to Work in Conjunction with InterSystems Products
Feature Tracker Collects Usage Statistics

Monitoring

About...
Monitoring Guide

Monitoring InterSystems IRIS Using the Management Portal
Using the InterSystems Diagnostic Report
Using Log Monitor
Using System Monitor
Gathering Global Activity Statistics Using ^GLOSTAT
Monitoring System Performance Using ^PERFMON
Monitoring Routine Performance Using ^PROFILE
Examining Routine Performance Using ^%SYS.MONLBL
Monitoring Block Collisions Using ^BLKCOL
Monitoring Performance Using ^SystemPerformance
Monitoring Performance Using ^mgstat
Monitoring Processes Using ^PERFSAMPLE
History Monitor
Monitoring InterSystems IRIS Using SNMP
Monitoring InterSystems IRIS Using Web Services
Monitoring InterSystems IRIS Using REST API
Monitoring InterSystems IRIS Using the irisstat Utility

Error Reference

General Error Messages
SQL Error Messages
TSQL Error Messages
System Error Messages
Messages Related to Productions

System Alerting and Monitoring Application

Specialized System Tools and Utilities

Introduction
Using System Classes for National Language Support
Customizing Start and Stop Behavior with ^%ZSTART and ^%ZSTOP Routines
Extending Languages with ^%ZLANG Routines
Controlling InterSystems IRIS from a Windows Client
Using ^GBLOCKCOPY for Fast Global Copies
Using Switches
Notes on Managing InterSystems IRIS via Routines
Process Management
Using cvendian for Byte Order Conversion

Architecture

About...
Mirroring and High Availability

About...
High Availability Solutions
High Availability Guide

Failover Strategies for High Availability
Mirroring Overview
Mirroring Architecture and Planning
Configuring Mirroring
Managing Mirroring
Mirror Outage Procedures

Scalability

About...
First Looks

Scaling for User Volume
Scaling for Data Volume

Scalability Guide

InterSystems IRIS Scalability Overview
Vertically Scaling InterSystems IRIS
Horizontally Scaling for User Volume with Distributed Caching
Horizontally Scaling for Data Volume with Sharding

Resiliency and Data Integrity

About...
First Look
Data Integrity Guide

Introduction to Data Integrity
Write Image Journaling and Recovery
Backup and Restore
Journaling
Data Consistency on Multiple Systems

Security

About...
About InterSystems Security
System Management & Security
Securing Your Instance

Security Strategy
Prepare for InterSystems Security
Tighten Security for an Instance
Security Advisor
Secure InterSystems Processes and Operating-System Resources
Checklist for Hardening Your Deployment

Security Tutorial

Authentication

Authentication Mechanisms
InterSystems Authentication Components and Process
Connection Tools and Access Modes
InterSystems Services
Specifying Authentication Mechanisms
Two-Factor Authentication
Users
Predefined Users
Cascading Authentication
Kerberos Authentication
Operating System Based Authentication
Instance Authentication
Example One: %Service_Console
Example One: %Service_Console (cont.)
Example One: %Service_Console (cont.)
Example One: %Service_Console (cont.)
Example Two: Web
Example Two: Web (cont.)
Delegated Authentication
Delegated Authentication Setup
ZAuthenticate
LDAP Authentication
LDAP Authentication Configuration
Recap

Authorization

Overview
Assets and Resources
Privileges
Public Privileges
Privileges, Roles, and Users
Database Resources
Namespaces
Example Setup
Example One: %Developer and %Operator Roles
Example Two: %Development Resource
Example Three: %DB_USER Resource
Example Four: $SYSTEM.Security.Check
Recap

Securing Applications

Overview
Three Types of Application Definitions
Properties of Application Definitions
Web Application Definitions
Example Setup
Example Setup (cont.)
Example One: Disabling an Application
Example Two: Protecting an Application with a Resource
Example Three: Application Roles
Example Four: Matching and Target Roles
Privileged Routine Applications
Example Setup
Example Setup (cont.)
Example: Creating a Privileged Routine Application Definition
Example: Adding a Routine
Example: Adding Application Roles
Example: Executing the Privileged Routine Application
Java, .NET, and Other Applications
Recap

Connection Tools, Access Modes, Services
Code for Authorization Example
Code for Authentication Example
Code for Privileged Routine Example
Creating a User
Creating a Resource
Creating a Role
Adding a User to a Role

Security for Developers

About...
SOAP Security

Introduction
Setup and Other Common Activities
Creating and Using Policies
WS-Policy Configuration Class Details
Adding Security Elements Manually
Adding Timestamps and Username Tokens
Encrypting the SOAP Body
Encrypting Security Header Elements
Adding Digital Signatures
Using Derived Key Tokens for Encryption and Signing
Combining Encryption and Signing
Validating and Decrypting Inbound Messages
Creating Secure Conversations
Using WS-ReliableMessaging
Creating and Adding SAML Tokens
Troubleshooting Security Problems
Details of the Security Elements

SQL Security
Command-Line Security Utilities

Authentication and Authorization

About...
First Looks

Role-Based Access Control
LDAP

Authentication Guide

Introduction
Kerberos Authentication
Operating System–Based Authentication
Instance Authentication
Delegated Authentication
Two-Factor Authentication
Services
Advanced Topics

Authorization Guide

About InterSystems Authorization
Assets and Resources
Privileges and Permissions
Roles
User Accounts
Applications
Using Delegated Authorization

LDAP Guide

LDAP and InterSystems IRIS®
LDAP Authentication
LDAP Authorization
Other LDAP Topics

OAuth 2.0 & OpenID Connect

Overview of OAuth 2.0 and OpenID Connect
How InterSystems IRIS Supports OAuth 2.0 and OpenID Connect
Using an InterSystems IRIS Web Application as an OAuth 2.0 Client
Using an InterSystems IRIS Web Application as an OAuth 2.0 Resource Server
Using InterSystems IRIS as an OAuth 2.0 Authorization Server
Creating Configuration Items Programmatically
Implementing DirectLogin()
Certificates and JWTs (JSON Web Tokens)

Encryption

About...
First Looks

Database Encryption
Public Key Infrastructure

Public Key Infrastructure
Encryption Guide

About Managed Key Encryption
Key Management Tasks
Using Encrypted Databases
Using Data-Element Encryption
Protecting Against Data Loss
Handling Emergency Situations
Additional Encryption Information
FIPS 140–2 Compliance for Database Encryption

Cryptographic Standards

TLS Guide

About TLS
About Configurations
Configuring the InterSystems IRIS Superserver to Use TLS
Configuring InterSystems IRIS Telnet to Use TLS
Configuring Java Clients to Use TLS with InterSystems IRIS
Configuring .NET Clients to Use TLS with InterSystems IRIS
Configuring Studio to Use TLS with InterSystems IRIS
Connecting from a Windows Client Using a Settings File
Configuring InterSystems IRIS to Use TLS with Mirroring
Configuring InterSystems IRIS to Use TLS with TCP Devices
Configuring the Web Gateway to Connect to InterSystems IRIS Using TLS
Establishing the Required Certificate Chain

Auditing Guide

Embedded Language Development

About...
Data Model
Orientation Guide

Introduction to InterSystems IRIS Programming
A Closer Look at ObjectScript
Classes
Objects
Persistent Objects and InterSystems IRIS SQL
Namespaces and Databases
InterSystems IRIS Security
Localization Support
Server Configuration Options
What's That?
Rules and Guidelines for Identifiers
General System Limits
Numeric Computing in InterSystems Applications

Globals

About...
First Look
Multidimensional Data Access
Using Globals

Introduction
Global Structure
Using Multidimensional Storage (Globals)
SQL and Object Use of Multidimensional Storage
Managing Globals
Temporary Globals and the IRISTEMP Database

ObjectScript

About...
First Look
ObjectScript IDEs

Connecting an IDE
About Visual Studio Code
Using Studio

Introduction to Studio
Creating Class Definitions
Adding Properties to a Class
Adding Methods to a Class
Adding Class Parameters to a Class
Adding Relationships to a Class
Adding Queries to a Class
Adding Indices to a Class
Adding Projections to a Class
Adding XData Blocks to a Class
Adding SQL Triggers and Foreign Keys to a Class
Adding Storage Definitions to a Class
Working with CSP Files
Working with Routines and Include Files
Using the Studio Debugger
Using Studio Templates
Studio Menu Reference
Setting Studio Options
Frequently Asked Questions About Studio

Source Control Integration

Using Terminal

Introduction to the Terminal
Using the Terminal Interactively
Controlling the Appearance and Behavior of the Terminal
Using Terminal Scripts
Script Command Reference
Connecting to Remote Hosts
Using the Terminal in Batch Mode
Advanced Topics

Object Data Access
Using ObjectScript

Introducing ObjectScript
Syntax Rules
Data Types and Values
Variables
Operators and Expressions
Regular Expressions
Commands
Callable User-defined Code Modules
ObjectScript Macros and the Macro Preprocessor
Embedded SQL
Multidimensional Arrays
String Operations
Lock Management
Transaction Processing
Error Processing
Command-line Routine Debugging

Class Definitions

About...
Defining & Using Classes

Basic Ideas in Class Programming
Defining and Compiling Classes
Package Options
Defining and Referring to Class Parameters
Defining and Calling Methods
Working with Registered Objects
Introduction to Persistent Objects
Working with Persistent Objects
Defining Persistent Classes
Defining and Using Literal Properties
Working with Collections
Working with Streams
Defining and Using Object-Valued Properties
Defining and Using Relationships
Other Options for Persistent Classes
Defining Method and Trigger Generators
Defining and Using Class Queries
Defining and Using XData Blocks
Defining Class Projections
Defining Callback Methods
Using and Overriding Property Methods
Defining Data Type Classes
Implementing Dynamic Dispatch
Object-Specific ObjectScript Features
Using the Populate Utility
Using the %Dictionary Classes
Using the Object Synchronization Feature

Class Definition Reference

Class Definitions
Class Keywords
Foreign Key Keywords
Index Keywords
Method Keywords
Parameter Keywords
Projection Keywords
Property Keywords
Query Keywords
Trigger Keywords
XData Keywords
Storage Keywords

Classes Page

ObjectScript Reference

Symbols and Abbreviations
ObjectScript Commands
Routine and Debugging Commands
ObjectScript Functions
ObjectScript Special Variables
Structured System Variables

ObjectScript Tutorial

The Basics

Introduction
Class Methods
Terminal
VS Code - ObjectScript
Do Command
Class Methods and Routines
Method Details
Passing Arguments by Reference
Return and Quit Commands
Write Command
Read Command
Set Command
Operator Precedence
Syntax
Common Errors
Write (again) and Kill Commands
If Construct
Simple Conditions
Complex Conditions
Hands-On Exercise 1
Class Compilation
Controlling Execution Flow
$Case Function
For Construct
While and Do/While Constructs
Try/Catch Construct, and Throw Command
Multiple Purpose Characters
Hands-On Exercise 2
Recap of Part 1

The Good Stuff

Strings
Storing a String
Concatenation Operator
Pattern Matching and Regular Expressions
Pattern Matching Examples
String Functions
String Functions, continued
Lists
Compare Pieces and Lists
Setting Substrings, Pieces, and List Items
More List Functions
Bitstrings
Dates
Hands-On Exercise 3
JavaScript Object Notation (JSON)
Arrays
Ordered Trees
Ordered Trees, continued
Value and Existence, and the $Data Function
Viewing and Killing Arrays
Globals
$Increment and $Sequence Functions
Storage Method
Storage Method, continued
Example of Globals
Hands-On Exercise 4
Recap of Part 2

Using Globals

$Order Function
$Order Function, continued
Working With Indexes
$Order Loop
Nested $Order Loops
Starting Focused $Order Loops
Ending Focused $Order Loops
Hands-On Exercise 5
Conversion Functions
$Get Function
Hands-On Exercise 6
Database Integrity
Lock Command
Lock Command, continued
Lock Command and $Test
Transaction Processing
Hands-On Exercise 7
InterSystems IRIS Objects and SQL
Object Methods
Object Storage
SQL Queries
Recap Of Part 3

RightTriangle Example Class and Exercise Solutions

Right Triangle Example Class
Exercise 1: First Data Entry Class
Exercise 2: Second Data Entry Class
Exercise 3: Third Data Entry Class
Exercise 4: Storage Method
Exercise 5: First Lookup Class
Exercise 6: Second Lookup Class
Exercise 7: Third Lookup Class

%Status Values
Try-Catch
Finding Class References

InterSystems API Manager (IAM)

About...
First Look

About...
First Looks

InterSystems SQL
Optimizing SQL Performance

Using SQL

Introduction to InterSystems SQL
InterSystems SQL Basics
Language Elements
Identifiers
Defining Tables
Defining and Using Views
Relationships Between Tables
Modifying the Database
Querying the Database
Collation
Implicit Joins (Arrow Syntax)
Using Embedded SQL
Using Dynamic SQL
Using the SQL Shell Interface
Using the Management Portal SQL Interface
Importing SQL Code
Using Triggers
Defining and Using Stored Procedures
Storing and Using Stream Data (BLOBs and CLOBs)
Users, Roles, and Privileges
Importing and Exporting SQL Data

Optimizing SQL

Introduction to SQL Performance Optimization
Defining and Building Indices
Optimizing Tables
Cached Queries
Optimizing Query Performance
SQL Performance Analysis Toolkit
Interpreting an SQL Query Plan
SQL Statements
Frozen Plans

InterSystems SQL Reference

Symbols and Syntax Conventions
SQL Commands
SQL Commands for IntegratedML
SQL Predicate Conditions
SQL Aggregate Functions
SQL Window Functions
SQL Functions
SQL Unary Operators
SQL Reference Material

Using the InterSystems SQL Gateway

SQL Gateway Overview
Using the InterSystems SQL Gateway
Connecting the SQL Gateway via JDBC
Connecting the SQL Gateway via ODBC
Using the SQL Gateway Programmatically

Document Database

Introducing InterSystems IRIS Document Database (DocDB)
Managing Documents
REST Client Methods

About...
XML Tools

Introduction to InterSystems XML Tools
Writing XML Output from Objects
Importing XML into Objects
Representing an XML Document as a DOM
Encrypting XML Documents
Signing XML Documents
Using %XML.TextReader
Evaluating XPath Expressions
Performing XSLT Transformations
Customizing How the InterSystems SAX Parser Is Used
Generating Classes from XML Schemas
Generating XML Schemas from Classes
Examining Namespaces and Classes
XML Background

XML Projections

Introduction to Object-XML Projections
Projecting Objects to XML
Controlling Transformations of Values
Handling Empty Strings and Null Values
Controlling the XML Element and Attribute Names
Specifying Namespaces for Elements and Attributes
Controlling the Projection to XML Schemas
Advanced Options for XML Schemas
Special Topics
Summary of XML Projection Parameters

Web Services

About...
Web Gateway Configuration Guide

Installing the Web Gateway
Web Application Architecture
Web Servers for Microsoft Windows
Web Servers for UNIX, Linux, and macOS
Web Gateway Operation and Configuration
Alternative Configurations for Microsoft Windows
Alternative Configurations for UNIX, Linux, and macOS
Apache Considerations UNIX, Linux, and macOS
Building Apache for IBM AIX®
IIS Technical Notes
Using Web Applications with a Remote Web Server

SOAP

About...
Creating SOAP Web Services and Clients

Introduction to Web Services and Web Clients in InterSystems IRIS
Current Page: Creating SOAP Web Services
SOAP Message Variations
Creating Web Clients
SOAP Fault Handling
Using MTOM for Attachments
Using SOAP with Attachments
Adding and Using Custom Header Elements
Adding and Using WS-Addressing Header Elements
SOAP Session Management
Using the InterSystems IRIS Binary SOAP Format
Using Datasets in SOAP Messages
Fine-Tuning a Web Service in InterSystems IRIS
Fine-Tuning a Web Client in InterSystems IRIS
Troubleshooting SOAP Problems in InterSystems IRIS
Summary of Web Service URLs
Details of the Generated WSDLs
Details of the Generated Classes

REST and JSON

About...
First Look
REST Services

Introduction to Creating REST Services
Using the /api/mgmnt Service
Using the ^%REST Routine to Create REST Services
Using the %REST.API Class to Create REST Services
Modifying the Implementation Class
Modifying the Specification Class
Supporting CORS in REST Services
Using Web Sessions with REST
Securing REST Services
Discovering and Documenting REST APIs
Reference for the /api/mgmnt API
OpenAPI Properties in Use
Creating a REST Service Manually

REST API for Source Code

Introduction to the InterSystems IRIS Source Code File REST API
Source Code File REST API Tutorial
Source Code File REST API Reference

Using JSON

Introduction
Creating and Modifying Dynamic Entities
Iteration and Sparse Arrays
Working with Datatypes
Using the JSON Adaptor
Quick Reference for Dynamic Entity Methods

Internet Utilities

Introduction
Sending HTTP Requests
Sending and Receiving Email
Creating, Writing, and Reading MIME Messages
Using FTP
Sending and Receiving IBM WebSphere MQ Messages
Using SSH
Other InterSystems %Net Tools

I/O Device Guide

About I/O Devices
I/O Devices and Commands
Terminal I/O
Local Interprocess Communication
TCP Client/Server Communication
UDP Client/Server Communication
Sequential File I/O
Spool Device
Printers

Advanced Concepts

Locking & Concurrency
Bits & Bitstrings
Structured Logging
Semaphores
String Localization
Process Memory
Work Queue Manager
Secure Logins
Using %Library.File
%UnitTest Tutorial

Unit Testing Overview

What is a Unit Test?
Why Unit Test?
xUnit Testing Frameworks
Structure of %UnitTest and xUnit Frameworks
Test Automation
Test First Methodology
Red – Green – Refactor
Recap

Unit Testing with %UnitTest

What is %UnitTest?
Creating and Executing a Suite of Unit Tests
%UnitTest Classes
Assert Methods and Macros
Creating Classes to Use in the Examples
Example: Creating and Exporting a Test Class
Example: Executing a Test
Example: UnitTest Portal
Example: Viewing the Report in the Unit Test Portal
Setup and Tear Down
Example: Adding Setup and Tear Down Methods to a Test
Example: Executing a Test Using Setup and Tear Down Methods
Options for Executing Tests: Test Specs and Qualifiers
RunTest Examples
DebugRunTestCase
Exercises
Recap

API Index

Tools Index

Glossary

Complete Glossary of Terms

External Language Development

About...
Native APIs
Using InterSystems External Servers

Introduction to InterSystems External Servers
Working with External Languages
Managing External Server Connections
Customizing External Server Definitions
InterSystems External Server Requirements
Quick Reference for the ObjectScript $system.external Interface

Java

About...
First Looks

Java Gateway
Native API for Java
Java Object Persistence with XEP
JDBC and InterSystems Databases

Java Gateway

Introduction to the Java Gateway
Using Dynamic Object Gateways
Using the Java Gateway in a Production
Sample Code
Mapping Specification

Using Java with InterSystems Software

Document Overview
InterSystems Java Connectivity Options
Using the JDBC Driver
Configuration and Requirements
JDBC for Occasional Users
JDBC Quick Reference

Using the Native SDK for Java

Document Overview
Introduction to the Java Native SDK
Calling ObjectScript Methods and Functions
Using Java Inverse Proxy Objects
Working with Global Arrays
Transactions and Locking
Java Native SDK Quick Reference

Persisting Java Objects with InterSystems XEP

Introduction
Using XEP Event Persistence
XEP Quick Reference

Implementing Third Party APIs

Introduction
JDBC Driver Support
Apache Spark Support
Hibernate Support

JDBC

.NET

About...
First Looks

.NET Gateway
Native API for .NET
ADO.NET and InterSystems Products
.NET Object Persistence with XEP
ODBC and InterSystems IRIS

Using the Object Gateway for .NET

Object Gateway Architecture
Setting Object Gateway Server Properties
Running an Object Gateway Server
Using Dynamic Object Gateways
Creating Static Proxy Classes
Sample Code
Mapping Specification
Using the Object Gateway in a Production

Using .NET with InterSystems Software

Introduction
Connecting to the InterSystems Database
Configuration and Requirements
ADO.NET Managed Provider for Occasional Users
Using the Entity Framework Provider
Quick Reference for the .NET Managed Provider

Using the Native API for .NET

Introduction to the Native API
Calling ObjectScript Methods and Functions
Using .NET Reverse Proxy Objects
Working with Global Arrays
Transactions and Locking
Native API for .NET Quick Reference

Persisting .NET Objects with InterSystems XEP

Introduction
Using XEP Event Persistence
XEP Quick Reference

ODBC

About...
Using the InterSystems ODBC Driver

Overview
Defining an ODBC Data Source on Windows
Defining an ODBC Data Source on UNIX®
ODBC Installation and Validation on UNIX® Systems
ODBC Support for Python and Node.js
Logging and Environment Variables

Python

About...
First Look
Using the Native API for Python

Introduction to the Native API
Working with Global Arrays
Calling ObjectScript Methods and Functions
Native API Quick Reference for Python

Node.js

About...
First Look
Using the Native API for Node.js

Introduction to the Native API
Working with Global Arrays
Calling ObjectScript Methods and Functions
Native API Quick Reference for Node.js

Callin

The Callin Interface
Using the Callin Functions
Callin Function Reference

Callout

Introduction
Running Programs or System Commands with $ZF(-100)
Creating an InterSystems Callout Library
Invoking Callout Library Functions
InterSystems Callout Quick Reference

Interoperability Productions

About...
First Look
Introducing Interoperability Productions

Introduction to Interoperability Productions
Connectivity Options
Business Processes and Business Logic
Other Production Options

Preparing to Create Productions

Road Map to Using InterSystems IRIS Productions
Planning an InterSystems IRIS Server Deployment

Best Practices

Best Practices for Production Development
Design Model for a Routing Production
Converting Interfaces to Production Elements

Developing Productions

About...
Developing Productions Using ObjectScript

Introduction
Programming Business Services, Processes and Operations
Defining Messages
Defining Business Services
Defining Business Processes
Defining Business Operations
Defining an Alert Processor
Defining Data Transformations
Defining Business Metrics
Defining an Enterprise Message Bank
Using the Record Mapper
Using the Complex Record Mapper
Handling Batches of Records Efficiently
Less Common Tasks
Testing and Debugging
Deploying a Production
Life Cycle of a Production and Its Parts

Developing Productions Using Java and .NET

Introduction
Getting Started
About Business Hosts and Adapters
Messaging
Inbound Adapters
Outbound Adapters
Business Services
Business Processes
Business Operations
Running the External Server
PEX API Reference

BPL and DTL

First Look
Developing BPL Processes

About BPL Processes
Using the Business Process Designer
Syntax Rules
List of BPL Elements
Handling Errors in BPL

Developing DTL Transformations

Introduction to DTL Tools
Creating Data Transformations
Syntax Rules
Adding Assign Actions
Adding Other Actions
Testing Data Transformations

BPL and DTL Reference

BPL Elements
DTL Elements

Using a Production as an ESB

Enterprise Service Bus and Registry Overview
Intended Audiences
Accessing the Public Service Registry through the Public REST API
Administering the Public Service and External Service Registries
Configuring an ESB
Configuring ESB Services and Operations
Configuring an InterSystems IRIS System and Creating a Namespace
Configuring a Web Application for a Pass-through Business Service
Pass-through Service and Operation Walkthrough
Service Registry Public API Reference

Configuring, Managing, and Monitoring Productions

About...
Configuring Productions

Introduction to Configuration Tasks
Creating a Production
Adding Business Hosts
Configuring Settings
Configuring Alerts
Defining Reusable Items for Use in Settings
Defining Other Options for Productions
Configuring the Enterprise Message Bank
Identifying Enterprise Systems for Viewing and Monitoring
Creating Dashboards
Settings in All Productions

Managing Productions

Introduction to Managing Productions
Starting and Stopping Productions
Purging Production Data
Using the Archive Manager
Managing Workflow Roles, Users, and Tasks
Defining Publish and Subscribe Message Routing
Controlling Data Storage for Productions
Controlling Access to Management Portal Functions
Finding Information on Menu Items

Monitoring Productions

Core Concepts
Monitoring All Namespaces
Monitoring a Production
Viewing, Searching, and Managing Messages
Viewing the Event Log
Enabling Tracing
Viewing the Business Rule Log
Viewing Business Process Instances
Viewing the I/O Archive for a Production
Viewing Messages from Multiple Productions
Using the Enterprise Message Viewer
Using the Enterprise Message Bank
Viewing Interface Maps
Finding Interface References
Monitoring Alerts
Monitoring Activity Volume
Managing Port Usage

Push Notifications

Push Notifications Overview
Configuring and Using Push Notifications

Defining Workflows

Overview of Workflow within Productions
Developing a Workflow
Including Custom Features in a Workflow
Testing a Workflow
Exploring the Workflow Sample
Available Workflow Metrics

Testing Productions

Testing Productions Tutorial
Testing Productions

TestControl
Callback Methods
Auxiliary Methods
Parameters and Properties
Creating a Test - Summary
Executing a Test
Example Overview
Example: Example Production
Example: Production Test
Example: OnAfterProductionStart
Example: CheckResults
Example: CheckErrors
Example: Executing the Test
Recap

Creating Tutorial.ExampleOperation

Connecting Systems

About...
Supported Formats
Supported Protocols
Email Adapters

Introduction
Using the Email Inbound Adapter
Using the Email Outbound Adapter
Reference for Settings

File Adapters

Introduction
Using the File Inbound Adapter
Using the File Outbound Adapter
Using the File Passthrough Service and Operation Classes
Reference for Settings

FTP Adapters

Introduction
Using the FTP Inbound Adapter
Using the FTP Outbound Adapter
Reference for Settings

HTTP Adapters

About the HTTP Adapters
Using the HTTP Inbound Adapter
Using the HTTP Outbound Adapter
Reference for Settings

Java Messaging Service (JMS)

JMS Overview
Configuring and Using JMS Business Services and Operations
Creating Custom JMS Services and Operations Using the Adapter

IBM WebSphere MQ Adapters

About the IBM WebSphere MQ Adapters
Using the IBM WebSphere MQ Inbound Adapter
Using the IBM WebSphere MQ Outbound Adapter
Troubleshooting
Reference for Settings

MQTT Adapters

Introduction to Message Queuing Telemetry Transport (MQTT)
Using the MQTT Adapters
Configuring and Using the MQTT Passthrough Business Service and Operation
Reference for Settings

REST Services and Adapters

Overview of Using REST in Productions
Creating REST Services in Productions
Creating REST Operations in Productions

SOAP Services and Web Clients

About SOAP and Web Services
Creating a Web Service in a Production
Creating a Web Client in a Production
Configuring a Production for SOAP Services
Using the SOAP Inbound Adapter
Older Web Service Variation
Reference for Settings

SAP Java Connector

Overview
Setup Tasks
Using the SAP Java Connector

SQL Adapters

About the SQL Adapters
Using the SQL Inbound Adapter
Using the SQL Outbound Adapter
Creating Adapter Methods for SQL
Using Result Sets
Using Snapshots

TCP Adapters

Introduction
Using the Inbound TCP Adapters
Using the Outbound TCP Adapters
Special Topics
Reference for Settings

Managed File Transfer

First Look
MFT Services

Introduction
Prerequisites and Configuration
Enabling a Production to Use MFT Services
Using the MFT API for InterSystems IRIS

Routing EDIFACT, X12, and XML Documents

About...
Using Virtual Documents in Productions

Virtual Documents
Schema Definitions
Virtual Property Paths
Using Virtual Documents in a Production
Defining Search Tables
Controlling Message Validation
Creating Custom Schema Categories
Portal Tools
Syntax Guide for Virtual Property Paths
Common Settings

EDIFACT

Introduction
Available Tools
Configuring the Production
Additional Steps
Reference for Settings

Introduction
X12 Schemas and Available Tools
Configuring the Production
Creating an X12 Data Transformation
Handling X12 Interchanges
Reference for Settings

Introduction
Available Tools
Configuration Steps
Overview of Property Paths in XML Virtual Documents
Specifying Schema-dependent Paths for XML Virtual Documents
Specifying DOM-style Paths for XML Virtual Documents
Defining Data Transformations for XML Virtual Documents
Defining Rule Sets for XML Virtual Documents
Defining Search Tables for XML Virtual Documents
XML-Enabled Objects Compared to XML Virtual Documents
Reference for Settings

Developing Business Rules

About Business Rules
Introduction to the Rule Editor
Creating and Editing Rule Sets
Debugging Routing Rules
Utility Functions for Use in Productions

Analytics and Data Science

About...
InterSystems IRIS Adaptive Analytics
Business Intelligence

About...
BI Introduction

Introduction to Business Intelligence
Introduction to the Business Intelligence User Interfaces
Introduction to the Other Business Intelligence Tools
Business Intelligence Glossary

BI Modeling

Introduction
Basic Concepts
Summary of Model Options
Principles and Recommendations
Defining Models for InterSystems Business Intelligence
Compiling and Building Cubes
Defining Dimensions, Hierarchies, and Levels
Details of Defining Levels
Defining Properties
Defining Measures
Defining Listings
Defining Listing Fields
Defining Calculated Members
Defining a Named Set
Defining Subject Areas
Defining Listing Groups
Reference Information for Cube Classes
Reference Information for Subject Area Classes
Details for the Fact and Dimension Tables

BI Advanced Modeling

Defining Computed Dimensions
Defining Shared Dimensions and Compound Cubes
Defining Cube-Cube Relationships
Using Text Analytics in Cubes
Defining Term Lists
Defining Worksheets
Defining Quality Measures
Defining Basic KPIs
Defining KPIs with Filters and Listings
Defining Advanced KPIs
Defining Plug-ins
Using Cube Inheritance
Defining Intermediate Expressions
Other Options
Reference Information for KPI and Plug-in Classes
Generating Secondary Cubes for Use with Text Analytics

Using Dashboards and the User Portal

Introduction to the User Portal
Using the Portal Features
Orientation to Dashboards
Using Dashboards
Using the Pivot Analysis Window

BI Dashboards

Introduction to Dashboards
Creating and Modifying Dashboards
Specifying Common Widget Options
Adding Pivot Table Widgets
Adding Chart Widgets
Customizing the Appearance of a Chart Widget
Adding Meter Widgets
Adding Scorecard Widgets
Adding Other Widgets
Defining and Using Themes
Adding Widget Controls

Implementing InterSystems IRIS Business Intelligence

Overview
Performing the Initial Setup
Configuring Settings
Defining Data Connectors
Performance Tips
Defining Custom Actions
Accessing Dashboards from Your Application
Keeping the Cubes Current
Executing Business Intelligence Queries Programmatically
Performing Localization
Packaging Business Intelligence Elements into Classes
Creating Portlets for Use in Dashboards
Other Development Work
Setting Up Security
Using Cube Versions
How the Analytics Engine Works
Using the MDX Performance Utility
Diagnostics for InterSystems Business Intelligence
Other Export/Import Options
Business Intelligence and Disaster Recovery

BI Analyzer

Introduction to the Analyzer
Creating Pivot Tables
Filtering Pivot Tables
Defining Calculated Elements
Defining and Using Pivot Variables
Customizing Pivot Tables
Working with Pivot Tables
Performing Ad Hoc Analysis
Configuring InterSystems IRIS for PDF Output

Using MDX

Background
Introduction to MDX Queries
Working with Levels
Working with Dimensions and Hierarchies
Working with Sets
Tuples and Cubes
Filtering a Query
Adding Summaries
Creating Calculated Measures and Members

MDX Reference

Basic Rules
Expression Types
MDX Statements and Clauses
MDX Functions
Intrinsic Properties
NOW Member for Time Levels
Quick Function Reference

Power BI
BI Clients

Introduction
DeepSee.js
Business Intelligence REST API

BI Tutorial

Getting Started
Introduction to Cube Elements
Creating a Cube
Expanding the Cube Definition
Creating Subject Areas
Creating and Packaging Pivot Tables and Dashboards

Apache Spark

About...
Using the InterSystems Spark Connector

Document Overview
Introduction
Spark Connector Data Source Options
Using Spark Connector Extension Methods
Spark Connector Best Practices
Spark Connector Internals
Spark Connector Quick Reference

Machine Learning

About...
Using IntegratedML

Introduction to ML
IntegratedML Basics
Providers
ML Configurations
Model Maintenance
About AutoML
SQL Commands
SQL Functions

Text Analytics (Natural Language Processing)

About...
Text Analytics with InterSystems Products
Using NLP

Conceptual Overview
NLP Implementation
Domain Architect
REST Interface
Alternatives for Creating an NLP Environment
Loading Text Data Programmatically
Performance Considerations when Loading Texts
NLP Queries
Semantic Attributes
Stemming
Skiplists
Filtering Sources
Text Categorization
Dominance and Proximity
Custom Metrics
Smart Matching: Creating a Dictionary
Smart Matching: Using a Dictionary
User Interfaces
IRIS Natural Language Processing (NLP) Tools
iKnow Web Services
KPIs and Dashboards
Customizing NLP
Language Identification
Domain Parameters

SQL Search

About...
First Look
Using SQL Text Search

InterSystems SQL Search Tool
SQL Search REST Interface

Unstructured Information Management Architecture

About...
InterSystems IRIS and UIMA
Using UIMA

Overview

Predictive Modeling Markup Language
InterSystems Reports

Introduction
InterSystems Reports Designer
InterSystems Reports Server with InterSystems IRIS

Creating SOAP Web Services

This topic describes the basics of how to create a web service in InterSystems IRIS.

You can refer to a table that summarizes the URLs related to your web service.

Overview of InterSystems IRIS Web Services

To create a web service in InterSystems IRIS, you create a class that extends %SOAP.WebService , which provides all the functionality required to make one or more methods callable via the SOAP protocol. In addition, this class automates the management of SOAP-related bookkeeping, such as maintaining a WSDL document that describes a service.

Basic Requirements

To create a web service in InterSystems IRIS, create and compile an InterSystems IRIS class that meets the following basic requirements:

The class must extend %SOAP.WebService .
The class must define the SERVICENAME parameter. InterSystems IRIS does not compile the class unless it defines this parameter.
This class should define methods or class queries that are marked with the WebMethod keyword.

Important:

In most cases, web methods should be instance methods. Within a web method, it is often necessary to set properties of and invoke methods of the web service instance (as described in later topics) to fine-tune the behavior of the method. Because a class method cannot do these tasks, a class method is usually not suitable as a web method.
For any web methods, make sure that each value in the method signature has an XML projection. For example, suppose that your method had the following signature:
```
Method MyWebMethod(myarg as ClassA) as ClassB [ WebMethod ]
```
In this case, both ClassA and ClassB must have an XML representation. In most cases, this means that their superclass lists must include %XML.Adaptor ; see Projecting Objects to XML. InterSystems IRIS SOAP support provides special handling for collections and streams, as noted after this list.

The web method can specify the ByRef and Output keywords in the same way that ordinary methods do. (For information on these keywords, see the topic "Methods" in Defining and Using Classes.)
Consider the values that are likely to be carried within these arguments and return values. XML does not permit nonprinting characters, specifically characters below ASCII 32 (except for carriage returns, line feeds, and tabs, which are permitted in XML).

If you need to include any disallowed nonprinting character, specify the type as %Binary , %xsd.base64Binary (which is equivalent), or a subclass. This value is automatically converted to base–64 encoding on export to XML (or automatically converted from base–64 encoding on import).

Do not rely on the method signature to specify the default value for an argument. If you do, the default value is ignored and a null string is used instead. For example, consider the following method:

Method TestDefaults(val As %String = "Default String") As %String [ WebMethod ]

When you invoke this method as a web method, if you do not supply an argument, a null string is used, and the value "Default String" is ignored.

Instead, at the start of the method implementation, test for a value and use the desired default if applicable. One technique is as follows:

                                                      if                                                      arg                  =                  ""                                                      {                                                      set                                                      arg                  =                  "Default String"                                                      }

You can indicate the default value in the method signature as usual, but this is purely for informational purposes and does not affect the SOAP messages.

For any required arguments in a web method, specify the REQUIRED property parameter within the method signature. For example:
```
Method MyWebMethod(myarg as ClassA(REQUIRED=1)) as ClassB [ WebMethod ]
```

By default, any inherited methods are treated as ordinary methods, even if a superclass marks them as web methods (but see "Subclassing an Existing InterSystems IRIS Web Services," later in this topic).

Input and Output Objects That Do Not Need %XML.Adaptor

In most cases, when you use an object as input or output to a web method, that object must extend %XML.Adaptor . The exceptions are as follows:

If the object is %ListOfDataTypes , %ListOfObjects , %ArrayOfDataTypes , %ArrayOfObjects , or a subclass, the InterSystems IRIS SOAP support implicitly treats the object as if it included %XML.Adaptor . You do not need to subclass these classes. However:

You must specify ELEMENTTYPE within the method signature, as follows:

                        Method                                                                        MyMethod                        ()                                                                        As                                                                        %ListOfObjects                        (                        ELEMENTTYPE                        =                        "MyApp.MyXMLType"                        )                                                                        [                        WebMethod                        ]                        {                                                                        //method implementation                        }

Or, in the case of an input argument:

                        Method                                                                        MyMethod                        (                        input                                                                        As                                                                        %ListOfObjects                        (                        ELEMENTTYPE                        =                        "MyApp.MyXMLType"                        )                        )                                                                        [                        WebMethod                        ]                        {                                                                        //method implementation                        }

If the class that you name in ELEMENTTYPE is an object class, it must inherit from %XML.Adaptor .

If the object is one of the stream classes, the InterSystems IRIS SOAP support implicitly treats the object as if it included %XML.Adaptor . You do not need to subclass the stream class.

If it is a character stream, the InterSystems IRIS SOAP tools assume that the type is string. If it is a binary stream, the tools treat it as base-64–encoded data. Thus it is not necessary to supply type information.

Using Result Sets as Input or Output

You can use result sets as input or output, but your approach depends on the intended web clients.

If both the web service and client are based on InterSystems IRIS or one is based on .NET, you can use the specialized result set class, %XML.DataSet , which is discussed in the topic "Using Datasets in SOAP Messages." Or you can use a class query as a web method. The XML representation is automatically the same as for %XML.DataSet .
To output results of a query so that a Java-based web client can work with it, use a %ListOfObjects subclass; there is an example in SOAP.Demo in the SAMPLES namespace.

Simple Example

This section shows an example web service, as well as an example of a request message that it can recognize and the corresponding response message.

First, the web service is as follows:

              ///                                          MyApp.StockService              Class                                          MyApp              .              StockService                                          Extends                                          %SOAP              .              WebService                                          {              ///                                          Name of the WebService.              Parameter                                          SERVICENAME                                          =                                          "StockService"              ;              ///                                          TODO: change this to actual SOAP namespace.              ///                                          SOAP Namespace for the WebService              Parameter                                          NAMESPACE                                          =                                          "http://tempuri.org"              ;              ///                                          Namespaces of referenced classes will be used in the WSDL.              Parameter                                          USECLASSNAMESPACES                                          =                                          1              ;              ///                                          This method returns tomorrow's price for the requested stock              Method                                          Forecast              (              StockName                                          As                                          %String              )                                          As                                          %Integer                                          [              WebMethod              ]              {                                          // apply patented, nonlinear, heuristic to find new price                                          Set                                          price                                          =                                          $Random              (              1000              )                                          Quit                                          price              }              }

When you invoke this method from a web client, the client sends a SOAP message to the web service. This SOAP message might look like the following (with line breaks and spaces added here for readability):

              <?              xml                                          version              =              "1.0"                                          encoding              =              "UTF-8"                                          ?>              <              SOAP-ENV:Envelope                                          xmlns:SOAP-ENV              =              'http://schemas.xmlsoap.org/soap/envelope/'                                          xmlns:xsi              =              'http://www.w3.org/2001/XMLSchema-instance'                                          xmlns:s              =              'http://www.w3.org/2001/XMLSchema'              >                                          <              SOAP-ENV:Body              >                                          <              Forecast                                          xmlns              =              "http://tempuri.org"              >                                          <              StockName                                          xsi:type              =              "s:string"              >              GZP              </              StockName              >                                          </              Forecast              >                                          </              SOAP-ENV:Body              >              </              SOAP-ENV:Envelope              >

Note that the message body (the <SOAP-ENV:Body> element) includes an element named <Forecast>, which is the name of the method that the client is invoking. The <Forecast> includes one element, <StockName>, whose name is based on the argument name of the web method that we are invoking. This element contains the actual value of this argument.

The web service performs the requested action and then sends a SOAP message in reply. The response message might look like the following:

              <?              xml                                          version              =              "1.0"                                          encoding              =              "UTF-8"                                          ?>              <              SOAP-ENV:Envelope                                          xmlns:SOAP-ENV              =              'http://schemas.xmlsoap.org/soap/envelope/'                                          xmlns:xsi              =              'http://www.w3.org/2001/XMLSchema-instance'                                          xmlns:s              =              'http://www.w3.org/2001/XMLSchema'              >                                          <              SOAP-ENV:Body              >                                          <              ForecastResponse                                          xmlns              =              "http://www.myapp.org"              >                                          <              ForecastResult              >              799              </              ForecastResult              >                                          </              ForecastResponse              >                                          </              SOAP-ENV:Body              >              </              SOAP-ENV:Envelope              >

These examples do not include the HTTP headers that precede the SOAP message itself.

Creating a Web Service

You can create web services in any of the following ways:

By creating a new class or editing an existing class to follow the requirements described earlier in this topic
By using the Web Service Wizard
By using the SOAP Wizard with an existing WSDL
By subclassing one or more InterSystems IRIS web services

Using the Web Service Wizard

The Web Service Wizard generates a simple stub.

Click File > New.

This displays the New dialog box.
Click the General tab.
Click New Web Service and then click OK.

This displays a wizard.
Enter values for the package name, class name, and web service name. These are required.
Optionally edit the namespace URI (or change this initial value later). This is the XML namespace, not the InterSystems IRIS namespace.
Optionally type a list of method names, on separate lines.
Click OK.

Now, you have a new web service class that contains stubs for the web methods. For example:

                ///                                                MyApp.StockService                Class                                                MyApp                .                StockService                                                Extends                                                %SOAP                .                WebService                                                {                ///                                                Name of the WebService.                Parameter                                                SERVICENAME                                                =                                                "StockService"                ;                ///                                                TODO: change this to actual SOAP namespace.                ///                                                SOAP Namespace for the WebService                Parameter                                                NAMESPACE                                                =                                                "http://tempuri.org"                ;                ///                                                Namespaces of referenced classes will be used in the WSDL.                Parameter                                                USECLASSNAMESPACES                                                =                                                1                ;                ///                                                TODO: add arguments and implementation.                ///                                                Forecast                Method                                                Forecast                ()                                                As                                                %String                                                [                                                WebMethod                                                ]                {                                                ;Quit "Forecast"                }                }

Using the SOAP Wizard with an Existing WSDL

In some cases, the WSDL has been designed already and it is necessary to create a web service that matches the WSDL; this is known as "WSDL-first development." In InterSystems IRIS, there are three steps to this development:

Use the SOAP Wizard to read the WSDL and to generate the web service and all supporting classes.

This wizard can also generate web client classes (which is more common).

For information on using this wizard, see "Using the SOAP Wizard," later in this book. Follow the steps described in that section and also select the Create Web Service option within the wizard.

Or use the %SOAP.WSDL.Reader class as described in "Using the %SOAP.WSDL.Reader Class."
Examine the generated classes to see if you need to change any %String values in the method signatures.

When the wizard reads a WSDL, it assumes that any string-type input or output can be represented in InterSystems IRIS as %String , which is not always true. In rare cases, some strings might exceed the maximum length string limit.

See "Adjusting the Generated Classes for Extremely Long Strings," later in this book.

Edit the methods in the generated web service so that they perform the desired actions.

Each method is initially a stub like the following example:

                    Method                                                            Add                    (                    a                                                            As                                                            Test                    .                    ns2                    .                    ComplexNumber                    ,                                                            b                                                            As                                                            Test                    .                    ns2                    .                    ComplexNumber                    )                                                            As                                                            Test                    .                    ns2                    .                    ComplexNumber                                                            [                                                            Final                    ,                                                            SoapAction                                                            =                                                            "http://www.mynamespace.org/GSOAP.AddComplexWS.Add"                    ,                                                            SoapBindingStyle                                                            =                                                            document,                                                            SoapBodyUse                                                            =                                                            literal,                                                            WebMethod                                                            ]                    {                                                            // Web Service Method Implementation Goes Here.                    }

The wizard includes compiler keywords such as Final and SoapBindingStyle. You should not change the values of these keywords.

If the WSDL includes WS-Policy elements, the wizard also generates a configuration class for the web service. The default configuration class name is the web service name, with Config appended to it. For information on WS-Policy, see Securing Web Services.

Subclassing an Existing InterSystems IRIS Web Service

You can create a web service by creating a subclass of an existing InterSystems IRIS web service class and then adding the SOAPMETHODINHERITANCE parameter to your class as follows:

                PARAMETER                                                SOAPMETHODINHERITANCE                                                =                                                1                ;

The default for this parameter is 0. If this parameter is 0, your class does not inherit the web methods as web methods. That is, the methods are available as ordinary methods but cannot be accessed as web methods within the web service defined by the subclass.

If you set this parameter to 1, then your class can use web methods defined in any superclasses that are web services.

Specifying Parameters of the Web Service

Make sure that your web service class uses appropriate values for the following parameters.

Note:

If you use the SOAP wizard to generate a web service from an existing WSDL, do not modify any of these parameters.

SERVICENAME

Name of the web service. This name must start with a letter and must contain only alphanumeric characters.

InterSystems IRIS does not compile the class unless the class defines this parameter.

NAMESPACE

URI that defines the target namespace for your web service, so that your service, and its contents, do not conflict with another service. This is initially set to "http://tempuri.org" which is a temporary URI often used by SOAP developers during development.

If you do not specify this parameter, the target namespace is "http://tempuri.org".

For an InterSystems IRIS web service, there is no way to put request messages in different namespaces. An InterSystems IRIS web client, however, does not have this limitation; see "Namespaces for the Messages," later in this book.

RESPONSENAMESPACE

URI that defines the namespace for the response messages. By default, this is equal to the namespace given by the NAMESPACE parameter.

For an InterSystems IRIS web service, there is no way to put response messages in different namespaces. An InterSystems IRIS web client, however, does not have this limitation; see "Namespaces for the Messages," later in this book.

TYPENAMESPACE

Namespace for the schema for the types defined by the web service. If you do not specify this parameter, the schema is in the target namespace of the web service (that is, either NAMESPACE or the default, which is "http://tempuri.org").

For an InterSystems IRIS web service, there is no way to put the request message types in different namespaces. An InterSystems IRIS web client does not have this limitation; see "Namespaces for Types," later in this book.

RESPONSETYPENAMESPACE

URI that defines the namespace for types used by the response messages. By default, this is equal to the namespace given by the TYPENAMESPACE parameter.

This parameter is used only if SoapBindingStyle equals "document" (the default).

For either an InterSystems IRIS web service or an InterSystems IRIS web client, the types for the response messages must all be in the same namespace.

SOAPVERSION

Specifies the SOAP version or versions advertised in the WSDL of the web service. Use one of the following values:

"" — Use this value for SOAP 1.1 or 1.2.
"1.1" — Use this value for SOAP 1.1. This is the default.
"1.2" — Use this value for SOAP 1.2.

When the web service receives a SOAP request, the SoapVersion property of the web service is updated to equal the SOAP version of that request.

See also "Restricting the SOAP Versions Handled by a Web Service," later in this book.

For details on how these values affect the WSDL, see the topic "Details of the Generated WSDLs."

About the Catalog and Test Pages

When you compile a web service class, the class compiler generates a convenient catalog page that you can use to examine the web service. This catalog page provides a link to a simple, limited test page (also generated). These pages are disabled by default. Enable them only in a test environment.

Access to the Catalog and Test Pages

If there is no web application for the namespace you are using, you cannot access the catalog and test pages; see "InterSystems IRIS Web Service as Part of a Web Application" in the previous topic. Also, by default, these pages are inaccessible. To enable access to them, open the Terminal, go to the %SYS namespace, and enter the following commands:

set ^SYS("Security","CSP","AllowClass",webapplicationname,"%SOAP.WebServiceInfo")=1 set ^SYS("Security","CSP","AllowClass",webapplicationname,"%SOAP.WebServiceInvoke")=1

Where webapplicationname is the web application name with a trailing slash, for example, "/csp/mynamespace/".

You can use these pages only if you are logged in as a user who has USE permission for the %Development resource.

Displaying the Catalog and Test Pages

The URL for the catalog page is constructed as follows:

base/csp/app/web_serv.cls

Here base is the base URL for your web server (including port if necessary), /csp/app is the name of the web application in which the web service resides, and web_serv is the class name of the web service. (Typically, /csp/app is /csp/ namespace.) For example:

http://localhost:52773/csp/samples/MyApp.StockService.cls

Notes on These Pages

The catalog page displays the class name, namespace, and service name, as well as the comments for the class and web methods. The Service Description link displays the generated WSDL; for information, see the section "Viewing the WSDL," later in this topic. The page then lists the web methods, with links (if you have the suitable permissions). The link for a given method displays a test page where you can test that method in a limited fashion.

Notes about this test page:

It does not enable you to see the SOAP request.
It does not test the full SOAP pathway. This means, for example, it does not write to the SOAP log that is discussed later in this topic.
It accepts only simple, literal inputs, so you cannot use it to call methods whose arguments are objects, collections, or datasets.

This book does not discuss this page further. To test your web service more fully, generate and use a web client as described later in this book.

Viewing the WSDL

When you use %SOAP.WebService to define a web service, the system creates and publishes a WSDL document that describes this web service. Whenever you modify and recompile the web service, the system automatically updates the WSDL correspondingly. This section discusses the following:

Viewing the WSDL and the URL at which the WSDL is published
Methods you can use to generate the WSDL as a static document

Also see "WSDL Support in InterSystems IRIS" in the first topic.

Important:

By definition, a web service and its web clients are required to comply to a common interface, regardless of their respective implementations (and regardless of any underlying changes in technology). A WSDL is a standards-compliant description of this interface. It is important to note the following:

In practice, a single SOAP interface can often be correctly described by multiple, slightly different WSDL documents.

Accordingly, the WSDL generated by InterSystems IRIS may have a slightly different form depending on the version of InterSystems IRIS. It is beyond the scope of this documentation to describe any such differences. InterSystems can commit only to the interoperability of web services and their respective clients, as required in the W3C specifications.
The W3C specifications do not require that either a web service or a web client be able to generate a WSDL to describe the interface with which it complies.

The system generates the WSDL document and serves it at a specific URL, for convenience. However, if the containing web application requires password authentication or requires an SSL connection, you may find it impractical to access the WSDL in this way. In such cases, you should download the WSDL to a file and use the file instead. Also, as noted previously, the generated WSDL does not contain any information about SOAP headers added at runtime. If you need a WSDL document to contain information about SOAP headers added at runtime, you should download the WSDL to a file, modify the file as appropriate, and then use that file.

Viewing the WSDL

To view the WSDL for the web service, use the following URL:

base/csp/app/web_serv.cls?WSDL

Note:

Any percent characters (%) in your class name are replaced by underscore characters (_) in this URL.

For example:

http://localhost:52773/csp/samples/MyApp.StockService.cls?WSDL

The browser displays the WSDL document, for example:

XML of a WSDL document

Important:

Not all browsers display the schema correctly. You might need to view the page source to see the actual schema. For example, in Firefox, right-click and then select View Source.

Generating the WSDL

You can also generate the WSDL as a static document. The %SOAP.WebService class provides a method you can use for this:

FileWSDL()

ClassMethod FileWSDL(fileName As %String, includeInternalMethods As %Boolean = 1) As %Status

Where fileName is the name of the file, and includeInternalMethods specifies whether the generated WSDL includes any web methods that are marked as Internal.

Suppressing Internal Web Methods from the WSDL

If the web service has web methods that are marked as Internal, by default the WSDL includes these web methods. You can prevent these methods from being included in the WSDL. To do so, do either of the following:

Use the FileWSDL() method of the web service to generate the WSDL; see the previous section. This method provides an argument that controls whether the WSDL includes internal web methods.
Specify the SOAPINTERNALWSDL class parameter as 0 in the web service class. (The default for this class parameter is 1.)