Flight Deck SOAP API Development Guide

The Signiant SOAP (Simple Object Access Protocol) API is a mechanism that allows client programs to 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 in the installer bundle.

Signiant Service WSDL and APIs

You can view the services available on the Signiant Manager at https://<Signiant_Manager_address>/signiant/services. The page also displays a link to the WSDL file associated with the service.

Note:<Signiant_Manager_address> is the fully qualified host name for the Manager.

More detailed information about the APIs provided by a specific service is available at https://<Signiant_Manager_address>/signiant/services/<service_name>.

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.

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

If SSL V3 is disabled on your Signiant Manager, and 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.

Replace use Net::SSL with 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();
}

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: 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 such as:

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

message = "Client.SchedulerError"

To determine the appropriate prompt names:

  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, rather than scheduled automatically.
  • ONCE
  • HOURLY
  • DAILY
  • WEEKLY
  • MONTHLY
  • MONTHEND: Job runs on the last day of every month.
  • YEARLY
  • FIRST, SECOND, THIRD, or FOURTH: Job runs 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

When passing an Agent parameter via SOAP, you may specify groups. Since groups are unique to an organization, 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 will return a SOAP fault message.

Errors may occur when processing a request itself, or may occur as the result of an outside condition, such as 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.

FaultCodes

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
  • password
  • jobName
  • jobGroupName
  • name: The name of the variable to be added
  • value: The value corresponding to the variable name

Return Value

Returns an integer indicating whether or not an error occurred in adding the variable. 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
  • password
  • jobName
  • jobGroupName
  • 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

  • delete
  • force: Run
  • kill
  • suspend: Suspend future runs
  • resume: Enable future runs
  • continue: Continue an interrupted job
  • setbwlimit: Set the bandwidth limit, bandwidth floor or the bandwidth ceiling on running jobs. Syntax: setbwlimit_<limit>:<floor>:<ceiling>.
    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 settings, use 0 (zero). To set only one or two of the values, pass in an empty string. Example: setbwlimits_:50000: to set only the floor.
    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
  • password
  • jobName
  • jobGroupName

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
  • password
  • jobName
  • jobGroupName

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
  • password
  • jobRunId

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: The job has existed past its scheduled end date.
  • SUSPENDED: The job has been manually suspended by a user.
  • INVALID: The 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 + character:

  • NEW: The job is newly-created and has not yet been evaluated by the Scheduler
  • IDLE: The job is not currently being executed.
  • RUNNING: The job is currently being executed.
  • RUN_QUEUED: The job is queued to be run.
  • COMPONENT_QUEUED: The job is running and a component is queued to be run.
  • DORMANT: The job has existed past its scheduled end date.
  • SUSPENDED: The job has been manually suspended by a user.
  • INVALID: The 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
  • password
  • jobName
  • jobGroupName
  • runNumber: The run number associated with the job for which you want to get statistics. If you specify 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). 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. 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). A value of 0 indicates an unlimited ceiling.
  • udp_floor: Specifies the current UDP floor (in bytes/seconds). 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
  • password
  • jobGroupName

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
  • password

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
  • password

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
  • password
  • jobGroupName

Return Value

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

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
  • password

Return Value

Returns a list ( hash) of the resource controls.

listResourceControlsVO

Returns the list of resource controls.

listResourceControlsVO(string username, string password)

Parameters

  • username
  • password

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
  • password
  • 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
  • password
  • 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
  • password
  • jobName
  • jobGroupName

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
  • password
  • jobName
  • jobGroupName

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
  • password
  • jobName
  • jobGroupName
  • 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. 0 indicates the job has been created and 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
  • password
  • jobName
  • jobGroupName
  • 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. 0 indicates the queued job was moved as requested. 1 indicates the job is not currently in the queue. 2 indicates the job is currently running and cannot be moved. 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
  • password
  • 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. 0 indicates the queued job was moved as requested. 1 indicates the job is not currently in the queue. 2 indicates the job is currently running and cannot be moved. 3 indicates the job cannot be moved ahead of the running job and will be queued to run next.

newJob

Creates 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
  • password
  • jobName
  • jobGroupName
  • 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
  • password
  • 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. 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
  • password
  • jobName
  • jobGroupName
  • 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. 0 indicates the variable was removed. 1 indicates that an error occurred.

resetAllJobVariables

Resets the entire list of variables associated with a job.

Note: If the job has previously set variables that the user has not reset with a new value, the variable will be reset to an empty value.

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

Parameters

  • username
  • password
  • jobName
  • jobGroupName
  • 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: Signiant recommends 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
  • password
  • jobName
  • jobGroupName
  • timeout: Time, in seconds, to wait before the SOAP call times out.

Return Value

Returns an integer indicating whether or not an error occurred when running the job. 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. 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. 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
  • password
  • jobName
  • jobGroupName
  • 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
  • password
  • jobName
  • jobGroupName
  • 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

You can ensure that SOAP initiated jobs are running properly by monitoring them using getJobActiveStatus and getLastJobResult.

To monitor a SOAP initiated job:

  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.
    Note: 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.
  5. If getLastJobResult returns an error, do the appropriate action (for example, resubmit or force the job).
  6. 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 allow clients to list template libraries available to specific users, create new job template libraries, and import/export job template libraries.

getJobTemplateLibraryNames

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

getJobTemplateLibrary(string username, string password)

Parameters

  • username: The username for the creator of the job template library.
  • password

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
  • newjobTemplateLibraryName: The name of the new job template library. The name can only contain alphanumeric and underscore characters.

Return Value

Returns 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
  • 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 for the creator of the job template library.
  • password
  • 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: If the name provided already exists, the existing Job Template Library is over-written. 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.