Connecting Web Services with Redwood Server
Web services can be created inside product on the Web Services tab of process definitions or chain definitions. You may specify a name, by default it is the name of the process definition or chain definition with a WS_
prefix. The WSURL is the external URL from which the web service is called, the default is the current URL used to connect to the central Redwood Server followed by the name of the web service (usually /api-soap/submit/WS_<Process_definition>?WSDL
. It is best to set the server name to the Fully Qualified Domain Name (FQDN) of the server to ensure that other processes can resolve the server. Note that the full URL can be found on the process definition under Published Web Services.
Example
The WSDL URL for process definition WS_MSLN_DB_BACKUP on the server pr3.example.com is as follows:
http://pr3.example.com:53100/redwood/api-soap/submit/WS_MSLN_DB_BACKUP?wsdl
Redwood Server has the following default web services:
- QueryJob1 - used to query a field of a process (status, return code, queue ...); available under
http://<server>:<port>/redwood/api-soap/query/Job/QueryJob1?WSDL
- QueryJob2 - used to query a field of a process, wait for it to reach a final status, and optionally retrieve output files; available under
http://<server>:<port>/redwood/api-soap/query/Job/QueryJob2?WSDL
- UpdateJob1 - used to set the status of a process (externally submitted asynchronous web service processes); available under
http://<server>:<port>/redwood/api-soap/update/Job/UpdateJob1?WSDL
Additional web services can be created inside product on the Web Services tab of process definitions or chains. You may specify a name, by default it is the name of the process definition or chain definition with a WS_
prefix. The WSURL is the external URL from which the web service is called, the default is the current URL used to connect to the central Redwood Server. It is best to set the server name to the Fully Qualified Domain Name (FQDN) of the server to ensure that other processes can resolve the server.
Parameters
Mandatory process definition parameters that have a default value are marked as optional from the web services side, as there is no need to fill the parameter; note that setting a mandatory process definition parameter which has a default value to a null value will prevent you from submitting the process, though.
Prerequisites
- The full URL to the WSDL
- credentials with necessary privileges to run the web service
- The license item Module.WebServices.Inbound must be set to
true
Aliases
You can set aliases to make the built-in web services available via a proxy. The aliases are stored in the Redwood Server registry entry at /configuration/webservices/aliases
. The key name should be the alias name of the web service and the value must be the actual hostname.
Values
Tab | Field | Description | Default Value |
---|---|---|---|
Web Services | Name | The name of the web service, must be unique. | The name of the process definition with aWS_prefix. |
Web Services | Description | An optional description of the web service. | |
Web Services | Documentation | An optional comment of the web service. | |
Web Services | Add Note | When checked, processes created by this web service will have a note attached, allowing you to easily distinguish processes submitted by web services from others. | false |
Web Services | Enabled | When checked, the web service is active and when called, will submit the job. | true |
Web Services | WSURL | The Redwood Server URL from the point of view of the web service client. | Current URL to Redwood Server |
Special Parameters
The following built-in SOAP-specific parameters are available; these will be filled by the caller:
SOAP_Inbound_Username
- the username used to authenticate with Redwood ServerSOAP_Inbound_WSName
- the web service nameSOAP_Inbound_IPAddress
- the remote IP addressSOAP_Inbound_Hostname
- the remote hostnameSOAP_Inbound_Protocol
- the protocol (http or https)
The following built-in SOAP-specific parameters are available to override the process description and note.
SOAP_Inbound_Description
- the description of the process; the default value is Submitted via web serviceSOAP_Inbound_WSName
SOAP_Inbound_JobNote
- a note for the process; the default value is Submitted via web serviceSOAP_Inbound_WSName
. Submitted from Remote IP AddressSOAP_Inbound_IPAddress
. Submitted by UserSOAP_Inbound_Username
.
Setting Time, Date, DateTime and DateTimeZone Parameters
Date-related parameters are handled differently by default for published web services and UpdateJob1. Published web services accept the ISO 8601 Time Data elements standard as implemented by the W3C that is customary in web services. UpdateJob1 honors the Format for the parameter, which means that you can configure the parameter to accept the W3C ISO 8601 syntax as well as any other syntax supported by Redwood Server which uses SimpleDateFormat with additional identifiers.
UpdateJob1
By default, the date you specify in DateTimeZone parameters with UpdateJob1 has to match the following pattern:
yyyy/MM/dd HH:mm:ss,SSS i
yyyy
- the four digit yearMM
- two digit monthdd
- two digit dayHH
- two digit hour/24mm
- two digit minutess
- two digit secondSSS
- three digit millisecondi
- Olson timezone name such as Europe/Paris
Example date:
2020/12/24 23:59:59,000 Europe/Amsterdam
You set the desired format in the Format field of the process definition parameter, see JavaDateFormats for more information on patterns.
Example pattern for W3C ISO 8601 with Offset:
yyyy-MM-ddTHH:mm:ssXXX
Published Web Services
Dates and times in published web services follow a subset of the ISO 8601 Time Data elements standard as implemented by the W3C.
The following is an excerpt out of the WSDL file of a published process definition:
<s:element minOccurs="0" maxOccurs="1" name="MyDate" type="s:dateTime"/>
<s:element minOccurs="0" maxOccurs="1" name="MyDateTime" type="s:dateTime"/>
<s:element minOccurs="0" maxOccurs="1" name="MyDateTimeZone" type="s:dateTime"/>
<s:element minOccurs="0" maxOccurs="1" name="MyTime" type="s:int"/>
As can be seen, MyDate
, MyDateTime
, and MyDateTimeZone
all take the same type s:dateTime
, however, MyDateTime
and MyDateTimeZone
take the full format whereas MyDate
is specified as 2023-09-28
. MyTime
takes an integer; the number of milliseconds since midnight.
note
Redwood Server will display dates defined using the W3C ISO 8601 syntax in the POSIX-compliant fashion using the Etc/GMT-/+
timezone syntax. Note that this syntax inverses the +
and -
from the non-etc timezones - essentially those you are usually familiar with. This results in GMT+1
to to be displayed as Etc/GMT-1
and vice-versa, for example.
W3C ISO 8601
The international standard ISO 8601 is used for times, dates, dates with time and timezones. W3C Date and Time Formats syntax table:
Symbol | Description |
---|---|
YYYY | Four-digit year. |
MM | A hyphen (-) followed by two-digit month. |
DD | A hyphen (-) followed by two-digit day of month. |
T | Literal T to separate date and time information. |
hh | Two-digit hour (00 through 23). |
mm | A colon (:) followed by two-digit minute (00 through 59). |
ss | (Optional) A colon (:) followed by two-digit second (00 through 59). |
s | (Optional) A comma , followed by one or more digits representing a decimal fraction of a second; requires two-digit second to be specified. |
TZD | time zone designator; UTC offset (+hh:mm or -hh:mm) or literal Z for UTC. |
Date Parameters
Date parameters are specified using the YYYY-MM-DD
format, for example, 2023-09-28
.
DateTime and DateTimZone Parameters
DateTime and DateTimeZone parameters must be formatted as YYYY-MM-DDThh:mm[:ss[,s]]TZD
; for example 2023-09-28T15:05:59+01:00
, 2023-09-28T15:05:59,234-01:00
, or 2023-09-28T15:05:59Z
.
Time Parameters
Time parameters are specified in milliseconds since the start of the day. For example, 35430000
evaluates to 09:50:30,000
.
To calculate the number of milliseconds now:
DateTimeZone dtzone = new DateTimeZone();
DateTimeZone dtzone2 = new DateTimeZone();
dtzone2.truncateDay();
long it = dtzone.getUTCMilliSecs() - dtzone2.getUTCMilliSecs();
jcsOut.println(it);
Array Parameters
Array parameters are set just like any other parameter, you simply specify more than one value in <sch:OutValue></sch:OutValue>
tags.
Example
Setting a parameter of type array of strings:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="scheduler.redwood.com">
<soapenv:Header/>
<soapenv:Body>
<sch:UpdateJobRequest>
<sch:JobIdentifier>123</sch:JobIdentifier>
<sch:JobParameters>
<sch:JobParameterValue>
<sch:Name>MyOutParameter</sch:Name>
<sch:OutValue>Value1</sch:OutValue>
<sch:OutValue>Value2</sch:OutValue>
</sch:JobParameterValue>
</sch:JobParameters>
</sch:UpdateJobRequest>
</soapenv:Body>
</soapenv:Envelope>
Using curl to Submit a Process
The following shell script uses curl to submit a process. The script takes a parameter, the name of the published web service, to submit the process.
#!/bin/sh
#Set Environment
ENDPOINT="http://pr1.example.com:53000/redwood/api-soap/submit/$1"
read -s -p "Enter Username: " user
echo ""
read -s -p "Enter Password: " passwd
echo ""
#Call the web service
USERPASSWD=`jecho -base64 $user:$passwd`
curl -H 'SOAPAction: "/redwood/api-soap/submit/$1"' -H "Content-Type: application/xml; charset=utf-8" -H "Authorization:Basic $USERPASSWD" --data @- "${ENDPOINT}" <<EOF
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:red="Redwood.customer.redwood.com">
<soapenv:Header/>
<soapenv:Body>
<red:SubmitJobParameters>
<red:Queue>System</red:Queue>
</red:SubmitJobParameters>
</soapenv:Body>
</soapenv:Envelope>
EOF
Submitting a process
You have a process that loads data from an Oracle database and you want to trigger it from a UNIX system. You have published a web service for it named WS_DATA_LOAD
. The above code has been copied into a file named submit.sh
that is on your path:
$ submit.sh WS_DATA_LOAD
Enter Username:Administrator
Enter Password:
<?xml version="1.0" encoding="UTF-8" standalone="no"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> \
<SOAP-ENV:Body><SubmitJobResponse xmlns="Redwood.customer.redwood.com"><JobId>123</JobId></SubmitJobResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>
$
Using PowerShell to Submit a Process
The following PowerShell script submits a process. The script takes a parameter, the name of the published web service, to submit the process.
<#Set Environment#>
$URI = "http://pr1.example.com:53000/redwood/api-soap/submit/" + $args[0]
Write-Debug "$URI"
$Username = Read-Host "Username"
$Entry = Read-Host "Password" -AsSecureString
$Password = [Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToGlobalAllocUnicode($Entry))
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${Username}:${Password}"))
$headers = @{
Authorization = "Basic $encodedCreds"
SOAPAction = "/redwood/api-soap/submit/" + $args[0]
}
$envelope = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:red="Redwood.customer.redwood.com">
<soapenv:Header/>
<soapenv:Body>
<red:SubmitJobParameters>
<red:Queue>System</red:Queue>
</red:SubmitJobParameters>
</soapenv:Body>
</soapenv:Envelope>'
Write-Debug $envelope
<#Call the web service #>
(Invoke-WebRequest -Uri $URI -ContentType "text/xml" -Headers $headers -Body $envelope -method POST ).Content
Submitting a process
You have a process that loads data from an Oracle database and you want to trigger it from a Windows system. You have published a web service for it named WS_DATA_LOAD
. The above code has been copied into a file named submit.ps1
that is on your path:
PS C:\Users\example>submit.ps1 WS_DATA_LOAD
Username: Administrator
Password: ***************
<?xml version="1.0" encoding="UTF-8" standalone="no"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body><SubmitJobResponse xmlns="Redwood.customer.redwood.com"><JobId>123</JobId></SubmitJobResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>
PS C:\Users\example>
See Also
- Integrating Redwood Server with Web Services
- Calling Web Services from within Redwood Server
- Asynchronous Web Services
- The Registry
- W3C ISO 8601 Implementation
webservice