Connecting Web Services with Redwood Server

You can create web services on the Published Web Services tab of the Edit Process Definition pop-up window. 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.

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 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 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-07-27. 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:

Date Parameters

Date parameters are specified using the YYYY-MM-DD format, for example, 2023-07-27.

DateTime and DateTimZone Parameters

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