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 Server
SOAP_Inbound_WSName - the web service name
SOAP_Inbound_IPAddress - the remote IP address
SOAP_Inbound_Hostname - the remote hostname
SOAP_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 service SOAP_Inbound_WSName
SOAP_Inbound_JobNote - a note for the process; the default value is Submitted via web service SOAP_Inbound_WSName. Submitted from Remote IP Address SOAP_Inbound_IPAddress. Submitted by User SOAP_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 year
MM - two digit month
dd - two digit day
HH - two digit hour/24
mm - two digit minute
ss - two digit second
SSS - three digit millisecond
i - 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-11-16. 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-11-16.

DateTime and DateTimZone Parameters

DateTime and DateTimeZone parameters must be formatted as YYYY-MM-DDThh:mm[:ss[,s]]TZD; for example 2023-11-16T15:05:59+01:00, 2023-11-16T15:05:59,234-01:00, or 2023-11-16T15: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>

Product Documentation

Connecting Web Services with Redwood Server

Example

Parameters

Prerequisites

Aliases

Values

Special Parameters

Setting Time, Date, DateTime and DateTimeZone Parameters

UpdateJob1

Published Web Services

note

W3C ISO 8601

Date Parameters

DateTime and DateTimZone Parameters

Time Parameters

Array Parameters

Example

Using curl to Submit a Process

Submitting a process

Using PowerShell to Submit a Process

Submitting a process

See Also