Redwood Server has the following built-in 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

QueryJob1

Queries properties of a process. By default returns all parameter and parameter values, its status and description. You specify any field, such as Queue to retrieve the queue of the process.

Parameter	Description	Multiplicity	Mandatory
Job ID	ID of the process to modify	1	x
JobField	Any field of the process	`0-<n>`

QueryJob2

Queries properties of a process. By default returns all parameter and parameter values, its status and description. You specify any field, such as Queue to retrieve the queue of the process. Additionally, you can retrieve the files and other process data.

Parameter	Description	Multiplicity	Mandatory
Job ID	ID of the process to modify	1	x
JobField	Any field of the job	`0-<n>`
JobFiles	Retrieve process files	`0-1`
JobData	Retrieve process data	`0-1`
WaitForFinal	Timeout to wait for the process to reach a final status	`0-1`

note

The WaitForFinal parameter is an integer, so limited to max_int or 2147483647; the web service returns as soon as either the process reaches a final status or WaitForFinal is reached.

UpdateJob1

Update process works exclusively on processes that have status Running and an external completion strategy.

Parameters

Parameter	Description	Multiplicity	Mandatory
Job ID	ID of the process to modify	1	x
Status	new status of the job	0-1
WaitForJob	let the caller wait for the process to complete	0-1
Description	new description for the process, will be displayed in the processes monitor	0-1
JobParameter/OutValue	out parameter value to set	`0-<n>`
JobParameter/Name	name of the out parameter	`0-<n>`	*Required if any other JobParameter field is set
JobParameter/Format	format of the parameter	`0-<n>`
JobNote	add a note to the job	`0-<n>`

note

Process ID is the only mandatory parameter; if this is the only parameter set, the result will be a no-op.

UpdateJob1 only works with running processes that have an external completion strategy. The code below illustrates the source of a simple RedwoodScript process definition for use with UpdateJob1:

Import com.redwood.scheduler.api.model.enumeration.CompletionStrategyType;
{
 //Set the completion strategy to External
jcsJobContext.setCompletionStrategy(CompletionStrategyType.External);
}

tip

You can publish this process definition as a web service which can then be called by your external system; once submitted it will remain in status Running until its status is set to a final status. This can be done using UpdateJob1 or RedwoodScript in Redwood Server.

Example

QueryJob1

Retrieve the queue of the process with ID 123

Parameter	Value
Job ID	123
JobField	Queue

QueryJob2

Retrieve the process files of the process with ID 123

Parameter	Value
Job ID	123
JobFiles	true

UpdateJob1

Create a process definition for use with UpdateJob1

Navigate to "Definitions > Processes".
Choose New Process Definition from the context-menu.
Select RedwoodScript and choose Next.
Fill RS_ExternalJob into the Name field.
Paste the above RedwoodScript code into the Source field of the process definition.
On the Parameters tab, add a new parameter named MyParameter, in the Direction field, select Out.
Choose Save & Close.
Locate RS_ExternalJob in the overview and choose Submit from the context-menu.
Select a queue and choose Submit, write down the ID. In the following examples, the ID 123 will be used, please adapt that value as necessary.

Set an Out parameter of process with ID 123

Parameter	Value
Job ID	123
JobParameter/JobParameterValue/Name	MyParameter
JobParameter/JobParameterValue/OutValue	Updated from an external web service

SOAP envelope of the above request:

<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>MyParameter</sch:Name>
               <sch:OutValue>Updated from an external web service</sch:OutValue>
            </sch:JobParameterValue>
         </sch:JobParameters>
      </sch:UpdateJobRequest>
   </soapenv:Body>
</soapenv:Envelope>

Set Array Parameters with UpdateJob1

Set an Out parameter (array of strings) of process with ID 123

Parameter	Value
Job ID	123
JobParameter/JobParameterValue/Name	MyParameter
JobParameter/JobParameterValue/OutValue	Updated from
JobParameter/JobParameterValue/OutValue	an external web service

SOAP envelope of the above request:

<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>MyParameter</sch:Name>
               <sch:OutValue>Updated from</sch:OutValue>
               <sch:OutValue>an external web service</sch:OutValue>
            </sch:JobParameterValue>
         </sch:JobParameters>
      </sch:UpdateJobRequest>
   </soapenv:Body>
</soapenv:Envelope>

Set Time, Date, DateTime, DateTimeZone Parameters

Set Out parameters of process with ID 123; note that the names include the data type of the parameter after the My prefix.

Parameter	Value
Job ID	123
JobParameter/JobParameterValue/Name	MyTime
JobParameter/JobParameterValue/OutValue	15:30:25
JobParameter/JobParameterValue/Name	MyDate
JobParameter/JobParameterValue/OutValue	2023/11/16
JobParameter/JobParameterValue/Name	MyDateTime
JobParameter/JobParameterValue/OutValue	2023/11/16 23:59:59,000
JobParameter/JobParameterValue/Name	MyDateTimeZone
JobParameter/JobParameterValue/OutValue	2023/11/16 23:59:59,000 Europe/Amsterdam

SOAP envelope of the above request:

<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>MyTime</sch:Name>
               <sch:OutValue>15:30:25</sch:OutValue>
            </sch:JobParameterValue>
            <sch:JobParameterValue>
               <sch:Name>MyDate</sch:Name>
               <sch:OutValue>2023/11/16</sch:OutValue>
            </sch:JobParameterValue>
            <sch:JobParameterValue>
               <sch:Name>MyDateTime</sch:Name>
               <sch:OutValue>2023/11/16 23:59:59,000</sch:OutValue>
            </sch:JobParameterValue>
            <sch:JobParameterValue>
               <sch:Name>MyDateTimeZone</sch:Name>
               <sch:OutValue>2023/11/16 23:59:59,000 Europe/Amsterdam</sch:OutValue>
            </sch:JobParameterValue>

         </sch:JobParameters>
      </sch:UpdateJobRequest>
   </soapenv:Body>
</soapenv:Envelope>

Multiple UpdateJob1 Requests

Update the description of process with ID 123 multiple times while the external process is running, set an out parameter value, finally, set the description and status

First call

Parameter	Value
Job ID	123
Description	0wned by external web service, Initializing

Second call

Parameter	Value
Job ID	123
Description	0wned by external web service, Runnning
JobParameter/JobParameterValue/Name	MyParameter
JobParameter/JobParameterValue/OutValue	Updated from an external web service

Last call

Parameter	Value
Job ID	123
Status	Completed
Description	0wned by external web service, Completed

UpdateJob1 Called from UNIX

Calling the web service from the UNIX command line. Note that if your Redwood Server uses HTTPS with a self-signed certificate, you have to pass -k to curl.

#! /bin/sh

#Set Environment
ENDPOINT="http://pr1.example.com:53000/redwood/api-soap/update/Job/UpdateJob1"
user=Administrator
passwd=mysecret
#Job-Speific
JOBID=123
DESCRIPTION="Updated by Curl"

#Call the web service
USERPASSWD=`jecho -base64 $user:$passwd`
curl -H 'SOAPAction: "update/Job/UpdateJob1"' -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:sch="scheduler.redwood.com">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:UpdateJobRequest>
         <sch:JobIdentifier>${JOBID}</sch:JobIdentifier>
         <sch:Description>${DESCRIPTION}</sch:Description>
      </sch:UpdateJobRequest>
   </soapenv:Body>
</soapenv:Envelope>
EOF

Notes

Authentication is done by setting a HTTP header to "Authorization:Basic <base64>", where base64 is ":" encoded in base64.

SOAPAction is different for the different built-in web services:

queryJob1 - "query/Job/QueryJob1"
queryJob2 - "query/Job/QueryJob2"
updateJob1 - "update/Job/UpdateJob1"

You need to inspect the WSDL to write the XML.

Setting Multiple Fields with UpdateJob1 from UNIX

Setting some more fields of the job:

#! /bin/sh

#Set Environment
ENDPOINT="http://pr1.example.com:53000/redwood/api-soap/update/Job/UpdateJob1"
user=Administrator
passwd=mysecret

#Job-Specific
JOBID=123
DESCRIPTION="Updated by Curl"
STATUS=Completed
PARAMETER=MyParameter
P_VALUE="Curled"
JOB_NOTE="Curl wrote this note"

#Call the web service
USERPASSWD=`jecho -base64 $user:$passwd`
curl -H 'SOAPAction: "update/Job/UpdateJob1"' -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:sch="scheduler.redwood.com">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:UpdateJobRequest>
         <sch:JobIdentifier>${JOBID}</sch:JobIdentifier>
         <sch:Status>${STATUS}</sch:Status>
         <sch:Description>${DESCRIPTION}</sch:Description>
         <sch:WaitForJob>true</sch:WaitForJob>
         <sch:JobParameters>
            <sch:JobParameterValue>
               <sch:Name>${PARAMETER}</sch:Name>
               <sch:OutValue>${P_VALUE}</sch:OutValue>
            </sch:JobParameterValue>
         </sch:JobParameters>
         <sch:JobNotes>
            <sch:JobNoteValue>
               <sch:JobNote>${JOB_NOTE}</sch:JobNote>
            </sch:JobNoteValue>
         </sch:JobNotes>
      </sch:UpdateJobRequest>
   </soapenv:Body>
</soapenv:Envelope>
EOF

Calling UpdateJob1 from Windows using VBS

You create the following two files and store them in the same directory.

Create a request.xml file with the following content:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="scheduler.redwood.com">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:UpdateJobRequest>
         <sch:JobIdentifier>strJobId</sch:JobIdentifier>
         <sch:Description>strDescription</sch:Description>
      </sch:UpdateJobRequest>
   </soapenv:Body>
</soapenv:Envelope>

Create a UpdateJob1.vbs file with the following content, adapt the process ID:

option explicit

Dim oXMLDoc, oXMLHTTP, oXMLEnv, wsResponse, fso, MyFile, FileName

Set oXMLHTTP = CreateObject("MSXML2.XMLHTTP.3.0")
Set oXMLDoc = CreateObject("MSXML2.DOMDocument")
Set fso = CreateObject("Scripting.FileSystemObject")

    ' Open the envelope file
    FileName = fso.GetAbsolutePathName(".") &"\request.xml"
     Set MyFile = fso.OpenTextFile(FileName, 1)
        oXMLEnv = MyFile.readAll
        oXMLEnv = replace(oXMLEnv, "strDescription", "Updated with VBS")
        oXMLEnv = replace(oXMLEnv, "strJobId", "123")
       'Wscript.echo("request: " & oXMLEnv)

        call oXMLHTTP.open("POST","http://pr1.example.com:53000/redwood/api-soap/update/Job/UpdateJob1",False, "Administrator", "MySecret")
 call oXMLHTTP.setRequestHeader("SOAPAction","update/Job/UpdateJob1")

 oXMLHTTP.send(oXMLEnv)
 if(oXMLHTTP.readyState = 4) then
   wsResponse = oXMLHTTP.responseText
   'Wscript.echo wsResponse
          Wscript.echo "Success!"
        else
          Wscript.echo("Request failed ...")
        end if

oXMLEnv = ""
wsResponse = ""
FileName = ""
MyFile.close
set MyFile = nothing
set fso = nothing
set oXMLDoc = nothing
set oXMLHTTP = nothing

webservice

Product Documentation

Built-in Web Services

QueryJob1

QueryJob2

note

UpdateJob1

Parameters

note

tip

Example

QueryJob1

QueryJob2

UpdateJob1

Set Array Parameters with UpdateJob1

Set Time, Date, DateTime, DateTimeZone Parameters

Multiple UpdateJob1 Requests

UpdateJob1 Called from UNIX

Setting Multiple Fields with UpdateJob1 from UNIX

Calling UpdateJob1 from Windows using VBS