Signiant Support

13.4 SOAP API Developers Guide Print


SOAP API Introduction

The Signiant SOAP (Simple Object Access Protocol) API is a mechanism that allows client programs to pro-grammatically interact with and execute APIs on a Signiant Manager. A SOAP client is required to perform the communication with the SOAP server (the Manager Web application). Examples using SOAP clients written in Perl are located in the /support/soapSamples directory found on your installer media.


Signiant Service WSDL and APIs

To view the services provided by the Signiant Manager, enter the following URL into a web browser:

https://<Signiant_Manager_address>/signiant/services

where <Signiant_Manager_address> is the fully qualified host name for the Manager. A web page listing all of the services available on the Manager appears. Additionally, a link to the WSDL file associated with the service will be shown.

To view more detailed information about the APIs provided by a specific service, use the following URL:

https://<Signiant_Manager_address>/signiant/services/<service_name>

where <service_name> is the name of the service whose details to view (i.e., "JobTemplateLibraryService"). Note that service names are case-sensitive. A web page listing the APIs provided by that service will be shown.

Security: Enabling and Disabling SSL V3

To improve Signiant Manager security, only TLS 1.1 and above are supported for Signiant web server communication. Signiant Agents use the highest level of supported TLS to ensure optimum security
and communication. If you want to run a Signiant Manager with an SSL protocol lower than TLS 1.1, use setMinimumSSLVersion.pl.

If you're using Internet Explorer 9 or 10 and want to enable TLS 1.1 or TLS 1.2, do the following:

  1. In the Tools menu, select Internet Options.
  2. On the Advanced tab, enable Use TLS 1.1 and Use TLS 1.2. You can optionally disable Use SSL 3.0.
  3. Click OK.

Note: to enable SSL V3, your Signiant Manager and Agents must be running version 11.4 or higher.

Because SSL V3 is disabled on your Signiant Manager and if you have written Perl scripts that use the Net::SSL Perl module for HTTPS communication, you must modify your Perl script to use IO::Socket::SSL module.

If you have the following line in your Perl script: use Net::SSL, do the following:

  1. Remove use Net::SSL.
  2. Insert the following:
    if (eval {require IO::Socket::SSL;1})
    {
         IO::Socket::SSL->import();
    
         IO::Socket::SSL::set_defaults(SSL_verify_mode => SSL_VERIFY_NONE);
    }
    else
    {
         require Net::SSL;
         Net::SSL->import();
    }
    							

If the SSL verify mode needs to verify the server certificate, insert the following:

if (eval {require IO::Socket::SSL;1})
{
     IO::Socket::SSL->import();

     my $caCertString = '<PEM encoded CA certificate string>';
     require IO::Socket::SSL::Utils;
     IO::Socket::SSL::Utils->import('PEM_string2cert');
     my $caCertHandle = PEM_string2cert($caCertString);
     IO::Socket::SSL::set_defaults(
                 SSL_verify_mode => SSL_VERIFY_PEER,
                 SSL_ca => [$caCertHandle]
                 );
}
else
{
     require Net::SSL;
     Net::SSL->import();
}

With these changes, your Perl program will work without any further modifications.


SOAP Variables

The following SOAP methods manipulate variables that are defined in a job template:

  • addJobVariable
  • removeJobVariable
  • resetAllJobVariables
  • setJobVariables
  • shortCreateJob
  • shortUpdateJob

Passing the variables over SOAP requires that they be passed as two SOAP encoded arrays.

Syntax:

my $variableNames = SOAP::Data->value(["{variable1name}","{variable2name}","{variable3name}"]);

my $variableValues = SOAP::Data->value(["{variable1value}","{variable2value}","{variable3value}"]);

Example:

In the following example, the job template being used has five variables defined: SrcAgent, TgtAgents, srcdir, tgtdir, comp and inc.

my $variableNames = SOAP::Data->value(["SrcAgent","TgtAgents","srcdir","tgtdir","comp","inc"]);

my $variableValues = SOAP::Data->value(["se-src1.senet.com", "se-tgt1.senet.com", "c:/input", "c:/temp", "Yes", "Yes"]);

Note: All variables must be passed as strings. With any of the methods that take arrays of variables, the values MUST be string (even if they are numeric).

For information on encoding the various prompt types, refer to the "Prompt Types" table in the Component Development Developer's Guide.


SOAP Job Parameters

Creating and starting jobs on a Signiant Manager requires that input values be specified.

To avoid ambiguity, Job variables require a fully qualified name. Failure to provide the appropriate name will result in SOAP faults like:

com.signiant.mobilize.service.SigniantFault info = "You must supply / choose a value for Prompt Name"

message = "Client.SchedulerError"

To determine the appropriate name do the following:

  1. Open the appropriate Job Template Library from within the list of Job Template Libraries.
  2. Right-click the Start Component corresponding to the Job and select View Web Services Info ....

    The values in the Name column are those that should be used.


SOAP Job Frequencies

Several SOAP methods require the frequency of a job's execution. This can be one of the following formats:

  • NONE or MANUAL

    specifies that this job can only be forced(not automatically scheduled).

  • ONCE

    specifies that this job is executed only once, and then becomes dormant.

  • HOURLY

    specifies that this job is executed every hour.

  • DAILY

    specifies that this job is executed once a day.

  • WEEKLY

    specifies that this job is executed once a week.

  • MONTHLY

    specifies that this job is executed every month.

  • MONTHEND

    specifies that this job is executed on the last day of every month.

  • YEARLY

    specifies that this job is executed every year.

  • FIRST, SECOND, THIRD, or FOURTH

    weekday specifies to execute this job on the specified day each month.

  • A number followed by nothing (to indicate minutes), or followed by one of the following letters:
    • H - hours
    • D - days
    • W - weeks
    • M - months
    • Y - years

     


SOAP Agent Groups

Groups may be specified when passing an Agent parameter via SOAP. However, a specific syntax is required to specifying the group since group names are only unique for an organization (i.e.. not system wide). Essentially, the group name must be prefixed with the organization ID:

<group_name>!<organization_number>

Example:

MXUsers!5


SOAP Faults

When an exception occurs while processing a SOAP request, the server while processing a request the server will return a SOAP fault message.

Errors may occur when processing a request itself, or may occur as the result of an outside condition (i.e. the database becoming unavailable).

The fault generated will have three fields describing the error in increasing level of detail for the client:

  • The faultCode is a string containing the internal code of the fault.
  • The faultString is a short description of the problem.
  • The detail contains detailed information about the problem.

The following lists faultCodes and an explanation of their likely causes:

  • Server.Misconfiguration

    There is a problem with the server configuration or a fatal error occurred at the server that is being communicated back to the client.

  • Client.XMLParseError 

    The server was unable to parse the SOAP request. There is a problem with the client's configuration.

  • Client.AuthenticationError 

    The server was unable to authenticate the user and password for this request. Make sure that the SOAP method contains those parameters, and that the client can properly send them.

  • Client.UnknownMethod

    The client attempted to make an unknown call to the server.

  • Client.InvalidParameter

    The client sent an invalid parameter to the server or the number of parameters is not correct.

  • Client.ScheduleError

    The server received an error from the scheduler with the job parameters specified. The server was unable to schedule that job with those parameters. The detail string identifies the reasons.


Scheduler Service

The Scheduler Service provides the following methods for scheduling jobs:

addJobVariable

Add a single variable value to a job.

addJobVariable(string username, string password, string jobGroupName, string jobName, string name, string value)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the job is executed.

  • jobName

    The name of the job

  • Name

    The name of the variable to be added.

  • Value

    The value corresponding to the variable name (Name).

Return Value

Returns an integer indicating whether or not an error occurred in adding the variable. Zero (0) indicates the argument was added: 1 indicates that an error occurred.

commandForJob

Send a command to a job.

commandForJob(string username, string password, string jobName, string jobGroupName, string command)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobName

    The name of the job.

  • jobGroupName

    The name of the job group within which the job is executed.

  • command

    The command to send to the job. This command is sent directly to the scheduling client. To determine what commands are valid, run

    dds_schclnt help

    . Valid commands are
    • delete
    • force (run)
    • kill
    • suspend (future runs)
    • resume (enable future runs)
    • continue (continue an interrupted job)
    • setbwlimit used to set the bandwidth limit, bandwidth floor or the bandwidth ceiling on running jobs. The syntax is: setbwlimit_<limit>:<floor>:<ceiling>. For example, setbwlimits_100000:50000:100000 sets the limit to 100,000 bytes/sec, the floor to 50,000 bytes/sec and the ceiling to 100,000 bytes/sec. To remove any of the settings, use 0 (zero). To set only one or two of the values (instead of all three), pass in an empty string. For example, if you just want to set the floor, use the following syntax: setbwlimits_:50000:. The old command setbwlimit_<limit> is still supported.

Return Value

Results returned from commands are not passed back to the SOAP client. Returns an integer indicating whether an error occurred in sending the command. Zero (0) indicates the command was sent: 1 indicates that an error occurred.

getActiveFilename

Retrieve the active filename for a job.

getActiveFilename(string username, string password, string jobName, string jobGroupName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobName

    The name of the job.

  • jobGroupName

    The name of the job group within which the job is executed.

Return Value

Returns the active filename value for the job.

getActiveStatus

Retrieve the active status message for a job.

getActiveStatus(string username, string password, string jobName, string jobGroupName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobName

    The name of the job.

  • jobGroupName

    The name of the job group within which the job is executed.

Return Value

Returns the active status message if the solution developer has provided one in the Job Template.

getJobRunStartTime

Retrieve the job run start time.

getJobRunStartTime(string username, string password, string jobRunId)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobRunId

    The ID for the job.

Return Value

Returns the start time for the job.

getActiveStatusMsg

Retrieve the active status message for a job (synonymous with getActiveStatus).

getActiveStatusMsg(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

see: getActiveStatus.

getJobActiveState

Returns the current state for a job.

getJobActiveState(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

Returns one of the following states:

  • NEW job is newly-created and has not yet been evaluated by the Scheduler
  • IDLE job is not currently being executed.
  • RUNNING job is currently being executed.
  • STARTING job is in the process of beginning execution.
  • RUN_QUEUED job is queued to be run.
  • COMPONENT_QUEUED job is running and a component is queued to be run.

getJobInfo

Returns the information pertaining to the specified job in the given job group.

getJobInfo(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

Returns a hash of all of the variables related to a given job including the Job Template Name, Job Template Library Name, as well as all of the job template specific parameters.

getJobInfoVO

Returns the information pertaining to the specified job in the given job group.

getJobInfoVO(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

Returns an Array of Key Value Objects of all of the variables related to a given job including the Job Template Name, Job Template Library Name, as well as all of the job template specific parameters.

getJobScheduledState

Returns the condition preventing automated job executions.

getJobScheduledState(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

Returns one of the following states:

  • DORMANT job has existed past its scheduled end date.
  • SUSPENDED job has been manually suspended by a user.
  • INVALID job has a syntax error or is missing information needed by the Scheduler.

getJobGroupId

Returns the Signiant Contract_ID for a given group.

getJobGroupId(string username, string password, string groupName)

Parameters

see: getActiveStatus.

Return Value

Returns the Contract_ID for the given Job Group

getJobStatus

Returns the status of the last run for this job.

getJobStatus(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

Returns a list of states separated by '+' characters:

  • NEW job is newly-created and has not yet been evaluated by the Scheduler
  • IDLE job is not currently being executed.
  • RUNNING job is currently being executed.
  • RUN_QUEUED job is queued to be run.
  • COMPONENT_QUEUED job is running and a component is queued to be run.
  • DORMANT job has existed past its scheduled end date.
  • SUSPENDED job has been manually suspended by a user.
  • INVALID job has a syntax error or is missing information required by the Scheduler.
  • INCOMPLETE: The Job has run and did not finish.
  • INTERRUPTED: The job has an entered an interrupted state.

getLastJobResult

Returns the exit code from the last scheduled occurrence of a job.

getLastJobResult(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

Returns the integer exit code of the last job execution.

getStats

Return information for a running job.

getStats(string username, string password, string jobName, string jobGroupName, int runNumber, string fields, string fieldSep, string recordSep)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobName

    The name of the job.

  • jobGroupName

    The name of the job group within which the job is executed.  

  • runNumber

    The run number associated with the job for which you want to get statistics. If you specify zero (0), the most recent run is used.

  • fields

    Specify fields as a comma-separated list of valid fields. For a list and description of the statistics fields, see the table below.

  • fieldSep

    The character you want to use to separate the list of fields returned (for example, comma). If you do not specify a fieldSep, a comma is used.

  • recordSep

    The character you want to use to separate the list of records (for example, "\n" for a new line). If you do not specify a recordSep, a semi-colon is used.

Values for "fields" Parameter Name:

  • agent_stat_time

    Specifies the controlling agent time (system epoch time in microseconds) when the statistic record was generated, equivalent to interval_end_time for running transfers in the job_run_stat_interval table.

  • agent_start_time

    Specifies the controlling agent process start-up time (system epoch time in microseconds) saved in the database as a timestamp.

  • agent_end_time

    Specifies the controlling agent process end time (system epoch time in microseconds) saved in the database as a timestamp.

  • bandwidth_throttle

    Specifies the bandwidth throttle being applied at the end of the reporting interval (in bytes/seconds). Note that a value of 0 indicates that no bandwidth throttling was being applied at the end of the reporting interval.

  • byte_count

    Specifies the total number of data bytes in the known files to transfer.

  • direction

    Report on the direction associated with this component run.

  • directories_deleted

    Specifies the number of directories explicitly deleted by the target agent. Note that it does not include files/directories implicitly deleted during (overlay) transfers.

  • directories_skipped

    Specifies the number of directories (as files) skipped.

  • directories_transferred

    Specifies the number of directories (as files) successfully transferred.

  • directory_count

    Specifies the known number of directories (as files) to transfer.

  • effective_bytes

    Specifies an aggregate value equal to "file_data_bytes" + "file_bytes_skipped" + "the sum of the data counts of all currently-active streams".

  • failed_directories

    Specifies the number of directories (as files) that failed to transfer.

  • failed_files

    Specifies the number of files that did not transfer.

  • file_attr_bytes

    Specifies the number of uncompressed file attribute bytes transferred.

  • file_attr_bytes_comp

    Specifies the number of compressed file attribute bytes transferred.

  • file_bytes_deleted

    Specifies the number of file data bytes deleted.

  • file_bytes_skipped

    Specifies the number of file data bytes not transferred because the files were skipped.

  • file_count

    Specifies the known number of files to transfer.

  • file_data_bytes

    Specifies the number of uncompressed file data bytes transferred.

  • file_data_bytes_comp

    Specifies the number of compressed file data bytes transferred.

  • files_deleted

    Specifies the number of files explicitly deleted by the target agent.

  • files_skipped

    The number of files that were not transferred. A file is skipped when it already exists on the target and is the same as the source (i.e., it has not changed).

  • files_transferred

    Specifies the number of files successfully transferred.

  • job_id

    The number Signiant uses to identify this instance of job.

  • mxpackage_id

    The mxpackage_id associated with this component.

  • names_cmd_end_time

    Specifies the time the names command has completed for a file transfer.

  • ntwk_bytes_ack

    The total number of bytes acknowledged.

  • ntwk_bytes_recvd

    Specifies the number of bytes received by the controlling agent from the network.

  • ntwk_bytes_sent

    Specifies the number of bytes sent by the controlling agent on the network.

  • ovhd_src_cchnl

    Control channel overhead source to target.

  • ovhd_src_mnfst_comp

    Specifies the number of compressed source-to-target file manifest overhead bytes.

  • ovhd_src_prtcl

    Specifies the number of source-to-target transfer protocol overhead bytes.

  • ovhd_src_rsync

    Specifies the number of non-data RSYNC overhead bytes flowing from source agent to target agent.

  • ovhd_tgt_cchnl

    Control channel overhead target to source.

  • ovhd_tgt_mnfst_comp

    Specifies the number of compressed target-to-source file manifest overhead bytes.

  • ovhd_tgt_prtcl

    Specifies the number of target-to-source transfer protocol overhead bytes.

  • ovhd_tgt_rsync

    Specifies the number of non-data RSYNC overhead bytes flowing from target agent to source agent.

  • package_name

    The name of the job template with which the job is associated. Click on the name to open the associated job template.

  • package_type

    Indicates the kind of template with which the job is associated (FILE_TRF, PROCESS_TRF, REMOTE_CMD).

  • proc_data_bytes_sent

    Specifies either the number of bytes (a) sent by the controlling (source) agent of a process push transfer or (b) received by the controlling (target) agent of a process pull transfer; or the number of bytes sent by the controlling (source) agent across all channels of a streaming transfer.

  • proc_data_bytes_unconsumed

    Specifies the number of bytes received by the target agent of a process transfer that were not delivered to the target data sink command.

  • remote_end_time

    Specifies the remote agent process end time (system epoch time in microseconds) saved in the database as a timestamp.

  • remote_start_time

    Specifies the remote agent start-up time (system epoch time in microseconds) saved in the database as a timestamp.

  • rsync_bytes_skipped

    Specifies the number of file data bytes not transferred because the RSYNC algorithm deemed them unchanged.

  • sf_bytes_recvd

    Specifies the number of bytes received by the controlling agent from the Security Framework (SF) layer.

  • sf_bytes_sent

    Specifies the number of bytes sent by the controlling agent to the Security Framework (SF) layer.

  • source_host

    The name of the host that initiates the transfer.

  • status

    Indicates the current state of a transfer (PENDING, RUNNING, COMPLETE, PAUSED).

  • stat_version

    Captures the actual stat_version for the job stat.

  • target_filebytes

    The total number of file bytes sent in the packet.

  • target_host

    The name of the host to which the data is being transferred.

  • time_est

    Estimated time of completion.

  • tnnl_data_bytes_recvd

    Specifies the number of bytes received by the controlling (source) agent across all channels of a streaming transfer.

  • tnnl_data_bytes_sent

    Specifies the number of bytes the controlling (source) agent has sent.

  • total_errors

    General error counter for all exceptions detected by or reported to the controlling agent with respect to the remote agent.

  • transfer_end_time

    Specifies the end time for transfers with the remote agent (system epoch time in microseconds) saved in the database as a timestamp.

  • transfer_rate

    Calculated transfer rate. A push equals "ntwk_bytes_sent/(transfer_end_time - transfer_start_time)/ 1000000". For pulls, "ntwk_bytes_recd" is used.

  • transfer_rate_max

    Highest transfer rate calculated across all reported stat records for this transfer. By default, stats are reported every 60 seconds. Transfer rate for a push equals "ntwk_bytes_sent/(transfer_end_time - transfer_start_time)/1000000". For pulls. "ntwk_bytes_recd" is used.

  • transfer_rate_min

    Lowest transfer rate calculated across all reported stat records for this transfer. By default, stats are reported every 60 seconds. Transfer rate for a push equals "ntwk_bytes_sent/(transfer_end_time - transfer_start_time)/1000000. For pulls, "ntwk_bytes_recd" is used.

  • transfer_start_time

    Specifies the start time for transfers with the remote agent (system epoch time in microseconds) saved in the database as a timestamp.

  • transport_type

    Indicates the kind of transfer (UDP, TCP).

  • udp_aggressiveness

    Indicates the UDP aggressiveness level, one of: (HIGH, MEDIUM, LOW).

  • udp_ceiling

    Specifies the current UDP ceiling (in bytes/seconds). Note that a value of 0 indicates an unlimited ceiling.

  • udp_floor

    Specifies the current UDP floor (in bytes/seconds) Note that a value of 0 indicates the default floor value, which is currently 40MB/s (5mb/s).

  • udp_header_size

    Specifies the number of header bytes in a UDP transport packet (for use in UDP byte count computation).

  • udp_payload_size

    Specifies the number of payload bytes in a UDP transport packet (for use in UDP byte count computation).

  • udp_pkts_ack

    The total number of UDP packets.

  • udp_pkts_recvd

    Specifies the total number of UDP packets received by both the controlling and remote agents.

  • udp_pkts_resent

    Specifies the total number of UDP packets resent by both the controlling and remote agents.

  • udp_pkts_rjctd

    Specifies the total number of UDP packets rejected by both the controlling and remote agents.

  • udp_pkts_sent

    Specifies the total number of UDP packets sent by both the controlling and remote agents.

  • unrecovered_errors

    Error counter for all unrecoverable exceptions declared by the controlling agent with respect to the remote agent.

  • rmt_cmd_twu

    The Total work units

  • rmt_cmd_wuc

    The number of work units completed.

Note: The following fields associated with the getStats method have been deprecated:

elapse_time, files_to_transfer, bytes_to_transfer, bytes_transferred, bytes_effective, bytes_incr_ovhd

Return Values

Job Template Name, Type, Src Agent, Tgt Agent are always returned as the first four fields of each record. Other fields are returned in the order they were specified.

listJobs

Returns the jobs contained in this job group.

listJobs(string username, string password, string jobGroupName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the job is executed.  

Return Value

Returns an array of all job names contained in the job group.

listGroups

Returns the list of job groups.

listGroups(string username, string password)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

Return Value

Returns a hash of the group names and their associated Contract_IDs.

listGroupsVO

Returns the list of job groups.

listGroupsVO(string username, string password)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

Return Value

Returns an Array of Key Value Objects of the group names and their associated Contract_IDs.

listQueuedJobs

Returns the jobs contained in this job group and their position in the queue. The currently running job's position is 0.

listQueuedJobs(string username, string password, string jobGroupName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the queued job is executed.  

Return Value

Returns a comma-separated, ordered list of all job names contained in the queued job group.

For example, "jobName1:0, jobName2:1, jobName3:2".

Note: Unscheduled jobs in the specified job group will NOT be returned.

listResourceControls

Returns the list of resource controls.

listResource(string username, string password)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

Return Value

Returns a list ( hash) of the resource controls.

listResourceControlsVO

Returns the list of resource controls.

listResourceControlsVO(string username, string password)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

Return Value

Returns a list (an Array of Key Value Objects) of the resource controls.

listResourceControlQueue

Returns the queue for a specified resource control.

listResourceControlQueue(string username, string password, string resourceControlName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • resourceControlName

    The name of the resource control.  

Return Value

Returns the queued list ( hash) for the named resource control. The values returned in each record are consumerId, job name, job group name, resource name, component name, component state, source agent, target agent, requesting agent , component type and order in the queue.

listResourceControlQueueVO

Returns the queue for a specified resource control.

listResourceControlQueueVO(string username, string password, string resourceControlName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • resourceControlName

    The name of the resource control.  

Return Value

Returns the queued list ( an Array of Key Value Objects) for the named resource control. The values returned in each record are consumerId, job name, job group name, resource name, component name, component state, source agent, target agent, requesting agent , component type and order in the queue.

listResourcesForJob

Returns the list of all resource controls currently affecting a job.

listResourceForJob(string username, string password, string jobGroupName, string jobName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the queued job is executed.  

  • jobName

    The name of the job.

Return Value

Returns the queued list ( hash) for the job. The values returned in each record are consumerId, job name, job group name, resource name, component name, component state, source agent, target agent, requesting agent, component type and order in the queue.

ListResourcesForJobVO

Returns the list of all resource controls currently affecting a job.

listResourceForJobVO(string username, string password, string jobGroupName, string jobName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the queued job is executed.  

  • jobName

    The name of the job.

Return Value

Returns the queued list ( an Array of Key Value Objects) for the job. The values returned in each record are consumerId, job name, job group name, resource name, component name, component state, source agent, target agent, requesting agent, component type and order in the queue.

modifyJobPriority

Modifies the priority of running or queued job.

modifyJobPriority(string username, string password, string jobGroupName, string jobName, string priority)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the queued job is executed.  

  • jobName

    The name of the job.  

  • priority

    The priority for the job. The valid priorities are:

    • low
    • medium
    • high
    • urgent
    • immediate

    Return Value

Returns an integer indicating whether or not an error occurred in modifying the job priority. Zero (0) indicates the job has been created and one (1) indicates that an error occurred.

moveJobInQueue

Moves the position of a queued job within a queued job group.

moveJobInQueue(string username, string password, string jobGroupName, string jobName, int offset)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the queued job is executed.  

  • jobName

    The name of the job.  

  • offset

    The number of positions to move the job in the queue. A negative offset moves the job ahead in the queue. A positive offset moves the job back in the queue.   

Return Value

Returns an integer indicating the result of the move. Zero (0) indicates the queued job was moved as requested. One (1) indicates the job is not currently in the queue. Two (2) indicates the job is currently running and cannot be moved. Three (3) indicates the job cannot be moved ahead of the running job and will be queued to run next.

moveJobInResourceQueue

Moves the position of a queued job within a resource control queue.

moveJobInResourceQueue(string username, string password, long consumerId, int offset)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • consumerId

    The unique identifier for the job that is queued ( provided by return record of the listResourceControlQueue call).   

  • offset

    The number of positions to move the job in the queue. A negative offset moves the job ahead in the queue. A positive offset moves the job back in the queue.

Return Value

Returns an integer indicating the result of the move. Zero (0) indicates the queued job was moved as requested. One (1) indicates the job is not currently in the queue. Two (2) indicates the job is currently running and cannot be moved. Three (3) indicates the job cannot be moved ahead of the running job and will be queued to run next.

newJob

Create a new job using default parameters.

The newJob method simply creates the job in a single step, but does not execute it. A client application must call different methods after the newJob command to specify parameters to the job including the scheduling parameters required by the scheduler. The job's status will be invalid until all required parameters are set.

newJob(string username, string password, string jobGroupName, string jobName, string jobTemplateLibraryName, string jobTemplateName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the job is executed.  

  • jobName

    The name of the job.

  • jobTemplateLibraryName

    The name of the template library in which the new job should exist. The template library is located within the user who has been specified.

  • jobTemplateName

    The name of the job template to be scheduled. The username being passed in as part of the SOAP newJob request. must be the owner of the job template library (otherwise, the job creation will always fail). In order to allow the job owner to be specified so that 'non-owners' (who still have access to job template libraries for the purpose of scheduling jobs) can create them, prepend the project name with the username of the user who created it followed by a + or !.

Return Value

Returns an integer indicating whether or not an error occurred in creating the job. Zero (0) indicates the job has been created: 1 indicates that an error occurred.

newJobGroup

Creates a job group using the provided name. You cannot create a job group with the name of an already existing job group.

newJobGroup(string username, string password, string groupName)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • groupName

    The name of the job group to create.  

Return Value

Returns an integer indicating whether or not an error occurred while adding the job group. Returns the Contract_ID for the given Job Group.

removeJob

Removes an existing job instance.

removeJob(string username, string password, string jobName, string jobGroupName)

Parameters

see: getActiveStatus.

Return Value

Returns an integer indicating whether or not an error occurred in removing the job. Zero (0) indicates the job was removed: 1 indicates that an error occurred.

removeJobVariable

Removes a variable from the list of variables for a job.

removeJobVariable(string username, string password, string jobGroupName, string jobName, string name)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the job is executed.  

  • jobName

    The name of the job.

  • name

    The name of the variable to be acted upon (for example, to be added, removed, and so on).

Return Value

Returns an integer indicating whether or not an error occurred in removing the variable. Zero (0) indicates the variable was removed: 1 indicates that an error occurred.

resetAllJobVariables

Resets (replace) the entire list of variables associated with a job.

Note: If the job had previously set variables, and the user did not reset them with a new value (did not specify the variable as a parameter) the variable will be reset to an empty value

resetAllJobVariables(string username, string password, string jobGroupName, string jobName, array variables array variableValues)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobGroupName

    The name of the job group within which the job is executed.  

  • jobName

    The name of the job.

  • variables

    The array of variable names used by the job.

  • variableValues

    The array of values corresponding to the variable names used by the job and corresponding to arrVariables. If you do not specify a frequency or start time variable, the default of none and now are used respectively.

Return Value

Returns an integer indicating whether or not an error occurred in resetting the variables. Zero (0) indicates the variables were reset: 1 indicates that an error occurred.

runJob

Runs the specified job. Note: we recommend you use commandForJob with the command option of force. See commandForJob for the complete list of parameters.

runJob(string username, string password, string jobName, string jobGroupName, int timeout)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobName

    The name of the job.

  • jobGroupName

    The name of the job group within which the job is executed.  

  • timeout

    How long to wait before the SOAP call times out, in seconds.

Return Value

Returns an integer indicating whether or not an error occurred when running the job. Zero (0) indicates the job started successfully: 1 indicates that an error occurred

setJobVariable

Specify a variable for a job.

setJobVariable(string username, string password, string jobGroupName, string jobName, string name, string value)

Parameters

see: addJobVariable.

Return Value

Returns an integer indicating whether or not an error occurred in setting the variable. Zero (0) indicates the variable was set: 1 indicates that an error occurred.

setJobVariables

Specify variables for a job.

setJobVariables(string username, string password, string jobGroupName, string jobName, array variables array variableValues)

Parameters

see: resetAllJobVariables.

Return Value

Returns an integer indicating whether or not an error occurred in setting the variables. Zero (0) indicates the variables were set: 1 indicates that an error occurred.

shortCreateJob

Creates a new job and set job parameters.

shortCreateJob(string username, string password, string jobName, string jobGroupName, string jobTemplateLibraryName, string jobTemplateName, string timezone, array variables, array variableValues)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobName

    The name of the job.

  • jobGroupName

    The name of the job group within which the job is executed.  

  • jobTemplateLibraryName

    The name of the template library in which the new job should exist. The template library is located within the user who has been specified.

  • jobTemplateName

    The name of the job template to be scheduled. The username being passed in as part of the SOAP newJob request. must be the owner of the Job Template Library (otherwise, the job creation will always fail). In order to allow the job owner to be specified so that 'non-owners' (who still have access to job template libraries for the purpose of scheduling jobs) can create them, prepend the project name with the username of the user who created it followed by a + or !.

  • timezone

    The timezone to use for any time values passed in to this method.

  • variables

    The array of variable names used by the job.

  • variableValues

    The array of values corresponding to the variable names used by the job and corresponding to arrVariables. If you do not specify a frequency or start time variable, the default of none and now are used respectively.

Return Value

Returns an integer indicating whether or not an error occurred in creating the job. Zero (0) indicates the job was created: 1 indicates that an error occurred.

shortUpdateJob

Updates the parameters for a job.

shortUpdateJob(string username, string password, string jobName, string jobGroupName, string timezone, array variables, array variableValues)

Parameters

  • username

    The username associated with the job.

  • password

    The password associated with the specified username.

  • jobName

    The name of the job.

  • jobGroupName

    The name of the job group within which the job is executed.  

  • timezone

    The timezone to use for any time values passed in to this method.

  • variables

    The array of variable names used by the job.

  • variableValues

    The array of values corresponding to the variable names used by the job and corresponding to arrVariables. If you do not specify a frequency or start time variable, the default values of none and now are used.

Return Value

Returns an integer indicating whether or not an error occurred in updating the job. Zero (0) indicates the job has been updated: 1 (one) indicates that an error occurred.


Monitoring SOAP Initiated Jobs

This chapter explains how to use getJobActiveStatus and getLastJobResult to monitor SOAP initiated jobs to ensure that they are running properly.

To monitor a SOAP initiated job, do the following:

  1. Submit the job you want to monitor. If the frequency is set to None, you'll need to force the job to run.
  2. Use getJobActiveState to return the job status. The job status will be one of the following:
    • NEW job is newly-created and has not yet been evaluated by the Scheduler
    • IDLE job is not currently being executed.
    • RUNNING job is currently being executed.
    • STARTING job is in the process of beginning execution.
    • RUN_QUEUED job is queued to be run.
    • COMPONENT_QUEUED job is running and a component is queued to be run.
  3. Repeat step 1 until the job moves from RUNNING to IDLE. (NEW and STARTING might be displayed, the job does not typically remain in either state for a length of time.)
  4. When the job is in the IDLE state, use getLastJobResult to view the exit code for the job. A 0 indicates job success. A positive value indicates a failure. (The return codes are the same as those displayed in the GUI.)
    • If getLastJobResult returns an error, do the appropriate action (for example, resubmit or force the job).
    • If the job stays in the NEW state for an extended period of time, use shortUpdateJob to reevaluate the job, use removeJob to delete the job, or use shortCreateJob to resubmit the job.

Job Template Library Service

The Job Template Library APIs allows clients to list template libraries available to specific users, create new job template libraries, and import/export job template libraries. Job Template Libraries in this instance excludes "Legacy Job Template Libraries" (i.e. pre-Signiant 8.0).

getJobTemplateLibraryNames

Returns the names of job template libraries available to the specified username.

getJobTemplateLibrary(string username, string password)

Parameters

  • username

    The username to be identified as the creator of the job template library.

  • password

    The password associated with the specified username.

Return Value

Returns a comma-separated list of Job Template Library names available to the specified user in the following format:

Creator!jobTemplateLibraryName

newJobTemplateLibrary

Creates a new Job Template Library on the Manager.  The username specified will be designated as the owner of the new Job Template Library.

newJobTemplateLibrary(string username, string password, string newJobTemplateLibraryName)

Parameters

  • username

    The username to be identified as the creator of the job template library.

  • password

    The password associated with the specified username.

  • newjobTemplateLibraryName

    The name of the new job template library.  The name can only contain alphanumeric characters and underscore characters.

Return Value

Returns zero (0) if the creation is successful or a SOAP fault if an error occurred. 

exportJobTemplateLibrary

Export a Job Template Library in XML format. 

exportJobTemplateLibrary(string username, string password, string jobTemplateLibraryName)

Parameters

  • username

    The username of the user performing the export.  This user must have read access to the Job Template Library to be exported.

  • password

    The password associated with the specified username.

  • jobTemplateLibraryName

    The name of the job template library to be exported.

Return Value

Returns the Job Template Library in XML format. A SOAP fault is returned if an error occurred.

importJobTemplateLibrary

Import an XML formatted Job Template Library. 

importJobTemplateLibrary(string username, string password, string jobTemplateLibraryXML)

Parameters

  • username

    The username to be identified as the creator of the job template library.

  • password

    The password associated with the specified username.

  • jobTemplateLibraryName

    The name to be given to the imported Job Template Library.

  • jobTemplateLibraryXML

    The UTF-8 encoded XML of the job template library to be imported.

Note: An existing Job Template Library will be over-written if the name provided already exists. Execution may take several seconds while the XML for the Job Template Library is parsed. 

Return Value

Returns the ID number of imported Job Template Library if no error occurred.  The command returns a SOAP fault if any errors occurred.