Connecting Web Services with RunMyJobs

You can create web services on the Published Web Services tab of a Job Definition's Published Web Services tab. 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 RunMyJobs 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 FQDN of the server to ensure that other Jobs can resolve the server. The full URL can be found on the Job Definition under Published Web Services.

Example

The WSDL URL for Job 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

RunMyJobs has the following default web services:

• QueryJob1: Used to query a field of a Job (status, return code, Queue ...); available under http://<server>:<port>/redwood/api-soap/query/Job/QueryJob1?WSDL
• QueryJob2: Used to query a field of a Job, 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 Job (externally submitted asynchronous web service Jobs). Available under http://<server>:<port>/redwood/api-soap/update/Job/UpdateJob1?WSDL.

You can create additional web services on the Web Services tab of Job or Workflow Definitions. You can specify a name. By default it is the name of the Job Definition or Workflow Definition with a WS_ prefix.

Parameters

Mandatory Job Definition Parameters that have a default value are marked as optional from the web services side, because there is no need to supply a value for them. However, setting a mandatory Job Definition Parameter which has a default value to a null value will prevent you from running the Job.

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 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 supplied by the caller.

• SOAP_Inbound_Username: The username used to authenticate with RunMyJobs.
• 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 Job description and note.

• SOAP_Inbound_Description: The description of the Job. The default value is Submitted via web serviceSOAP_Inbound_WSName
• SOAP_Inbound_JobNote: A note for the Job. 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 customery ISO 8601 Time Data elements standard as implemented by the W3C. 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 RunMyJobs (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

Set the desired format in the Format field of the Job Definition Parameter. For more information, see JavaDateFormats.

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 Job 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"/>

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 representing the number of milliseconds since midnight.

Note: RunMyJobs displays dates defined using the W3C ISO 8601 syntax in the POSIX-compliant fashion using the Etc/GMT-/+ timezone syntax. Note that this syntax inverts the + and - from the non-etc timezones. 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. 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.

#!/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 Job Definition

Assume you have a Job Definition 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 Job Definition

The following PowerShell script submits a Job Definition. The script takes a Parameter: the name of the published web service.

<#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

Running a Job Definition

Assume you have a Job Definition 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 RunMyJobs with Web Services
• Calling Web Services from Within RunMyJobs
• W3C ISO 8601 Implementation