If you are new to the SoftFab API, please read the section about the call mechanism first.
These are the currently available API functions:
How to call an API function from a wrapper-script is explained here.
If you would like to query or change a certain piece of information on the Control Center and there is currently no API call that offers the desired functionality, please let us know.
Aborts one or more named (if they exist) or all tasks in a list of jobs. Multiple tasks can be aborted in multiple jobs. The existence of all mentioned tasks is not enforced in all the jobs. The API call should be interpreted as: abort these tasks in these jobs if they exist. This means that under certain conditions it is possible that after return not even one task is aborted.
Possible associated waiting or running extraction tasks are not aborted.
- jobId: (multiple, at least one)
- The job ID of the job to abort tasks of.
- taskName: (optional, multiple)
- The names of the tasks to abort. If this argument is omitted, all tasks in the job will be aborted.
- onlyWaiting: (optional)
- Abort only tasks that are waiting: do not abort currently running tasks. Possible values are `true` and `false`. If absent `false` is implied.
On success 'Abort' returns an XML structure tagged by
<abortedtasks> with 0 or more
<taskref> task references; 1 for every successful aborted task.
- Abort the "build" task in the specified job.
- Abort all running and waiting tasks in two specified jobs.
- Abort all waiting tasks in the specified job.
Exports factory information in XML format. Next to the factory name the root URL, the Control Center version number and the names and sizes of all internal data tables are exported.
- Return all kind of monitoring information in XML format of "factory".
Queries the job history. The returned XML contains the matching job IDs; you can use the GetJobInfo API call to get detailed information about each job.
- ctabove: (optional)
- Only return jobs created on or after the given date. The format of the date is "yyyy-mm-dd", optionally extended with a time stamp in the format "hh:mm".
- ctbelow: (optional)
- Only return jobs created before the given date. The format of the date is "yyyy-mm-dd", optionally extended with a time stamp in the format "hh:mm".
- configId: (optional, multiple)
- Only return jobs created from the specified configuration(s).
- owner: (optional, multiple)
- Only return jobs owned by the specified user(s).
- target: (optional, multiple)
- Only return jobs that have the specified target(s).
- execState: (optional)
- Only return jobs in the given execution state. Possible values are
unfinished. If absent,
- Return the IDs of all jobs created in 2008 from the configuration "Regression tests" that ran to completion.
Exports job information in XML format.
- jobId: (mandatory)
- The job ID of the job to retrieve the job information from.
- Return all information in XML format about job "080104-1435-AF98".
Exports information of any resource in XML format. Currently the resource types are Task Runners and the customer defined resources. If no parameters are given all the resources will be exported.
- type: (optional, multiple)
- The type of resource to retrieve the information from. The resource types are defined by the customer or
"sf.tr"which is the definition for a Task Runner.
- name: (optional, multiple)
- The name of the resource to retrieve the information from. The current implementation allows different types of resource sharing the same name. This will change in future.
- Return information of all resources.
- Return information of all resources of type "sf.tr".
- Return information of all different kind of resources identified by the name "myresource".
- Return just the information of resource "sf.tr" with name "myresource".
- Return the information of all resources "sf.tr" and custom resource typed "mytype".
Filters records using tags. The output is in XML format and consists of a set of triples: (record ID, tag key, tag value).
- subject: (mandatory)
- The type of record to query. Valid values are
- key: (any number of times)
- Match only those records that have a value for the given keys. If no keys are specified, all keys match.
- value: (any number of times)
- Match only those records that have one of the given tag values. If no values are specified, all values match.
- List all tagged configurations and their keys and values. Configurations without any tags are omitted.
- List all passive schedules that have a CM trigger filter.
- List all task definitions that apply to requirement "R1" or requirement "R2".
Requests selected parameter values from all task definitions. Output is in XML format.
- param: (any number of times)
- The name(s) of the task parameters to list. If no names are specified, all task parameters are listed.
- Get all parameters and their values for all task definitions.
- Get the wrapper names and the values of parameter "SOURCE_ROOT" for all task definitions.
Marks a postponed inspection as done and stores the result.
- jobId: (mandatory)
- The ID of the job that the inspected task is part of. See the
- taskName: (mandatory)
- The name of the inspected task. See the
- result: (mandatory)
- The result of the inspection. Accepted values are "ok" (green), "warning" (orange) and "error" (red).
- summary: (optional)
- Human readable string describing the result in more detail. For example: "8 passed, 2 failed, 0 errors".
- data._key_: (optional)
- Any number of mid-level data key/value pairs can be stored by this API call.
This API call is now POST-only; example needs updating.
- Mark the task "inspect" in job "080706-1234-ABCD" as done. The inspection found problems, hence the result being "warning" and the summary "Some problems". Two mid-level data pairs are stored: "pass=8" and "fail=2".
Loads a configuration and inserts it into the job queue with all locators and parameters set to their default values.
- config: (mandatory)
- The name of the configuration to load.
- comment: (optional)
- Comment string that will be appended to the comment in the configuration.
- prod.name: (optional)
- Locator for input product name. For example:
prod.image=http://host/path/. Multiple locators can be specified on a single function call, but only for inputs that actually occur in the chosen configuration.
- local.name: (optional)
- Task Runner which has access to local input product name. For example:
- param.name: (optional)
- It is possible to pass any number of optional job parameters, which do not affect execution of the job, but may provide some extra features. These job parameters are mainly useful for the program processing notification mails (see below).
One optional parameter has special meaning. If
param.notify=_notification_ is specified then a notification message will be sent when the job is complete. The way the message is sent and its content are defined by the specified notification method.
Currently only e-mail notification method is supported. To use it the value of the notification parameter must have the form
mailto:_user_name@host_or_domain_name_. The notification message has subject
Job Complete and body of the following form:
id: 2004-03-10_13-02_197500 param.name1: value1 param.name2: value2 ... task.1.name = task1 task.1.result = result1 task.1.state = state1 task.2.name = task2 task.2.result = result2 task.3.state = state2 ...
param.notify itself is not included in the message.
This call is used to suspend and resume resources. Task Runnners are considered resources too, so it is possible to suspend (pause) and resume (unpause) them with this call.
- name: (multiple, at least one)
- The name of the resource to operate on.
- action: (mandatory)
- The action to perform: "suspend" or "resume".
The call is considered successful if the desired end state was reached. This means that suspending an already suspended resource or resuming a resource that was not suspended is considered a successful action.
This API call is now POST-only; example needs updating.
- Suspends the resource "toollicense".
- Resumes Task Runners "runner1" and "runner2".
This call is used to signal the start and end of a Human Intervention Point (HIP). A HIP can be used to suspend the execution of a mostly automated task until a human has performed a certain task. During a HIP, the task background is changed from blue into yellow, to indicate that the task will not make any progress until someone performs an action.
- jobId: (mandatory)
- The job ID of the job that contains the task to suspend. You can use the SF_JOB_ID variable for this.
- taskId: (mandatory)
- The task ID of the task to suspend. You can use the SF_TASK_ID variable for this.
- alert: (mandatory)
- Alert type. Currently, the only supported type is
In order to signal the end of the HIP the same API call should be made again with empty value for
More information on the HIP can be found in the document about semi-automatic testing.
Sets a flag that will cause a specified Task Runner to exit as soon as it becomes idle. This can be useful if you want to automatically reboot Factory PCs or if you want to reload automatically generated Task Runner configuration files.
- runnerId: (mandatory)
- The ID of the Task Runner to set the flag for. This Task Runner has to be of version 2.12.0 or higher.
Sets a flag that will cause a specified passive schedule to activate.
- scheduleId: (mandatory)
- The ID of the schedule to set the trigger flag for. This schedule has to be a passive schedule.
This chapter describes how to make calls to the SoftFab API. It applies to all API functions described above. If you want to do an HTTP request (call an API function) from a wrapper script, then please read here how to do this.
To call a function on the SoftFab API, you fetch a URL from the Control Center. The base of the URL is the same as the URL of the SoftFab web interface you use, typically
project is your project name. The function name is appended to the base URL. For example, if you want to call the
LoadExecuteDefault function, the complete URL would be
Arguments are usually passed as a query string that is appended to the URL. For example, to pass the parameter "config" with value "regression_test" and the parameter "comment" with value "Started from API", the last part of the URL would be
Note that characters other than alphanumerics have to be encoded if they occur in URLs, as described in RFC 1630. If you are doing the call from a programming language, there is a good chance the standard language already contains a method to perform URL encoding. For example, in Java there is
java.net.URLEncoder and in Python there is
In some cases a particular API call may need a more complex input data structure than it can easily be represented by URL query arguments. In those cases the API should be called using HTTP POST request with the data structure represented in XML format and sent as the request body of
text/xml content type or or as the value of one of the parts of
multipart/form-data content type. The documentation of the specific API function tells you if you should do an HTTP POST and what the XML message format is.
Fetching the constructed URL from the SoftFab Control Center will return data in XML format. This is the "return value" of the function. If the function call requested data, the response body will contain the data in XML format, see the function's documentation for details. If the nature of a particular API call implies only success/failure type of response then success is indicated by the response body containing
Failure is indicated by an HTTP error code. The human-readable part of the HTTP status line contains a brief description of the nature of the failure. The following HTTP status codes are used by the SoftFab API:
- 400 - Bad Request
- There is something wrong about the request. It can be a syntax error, a reference to a non-existing database record, an otherwise invalid value etc. See the human-readable part of the status line for details.
- 403 - Forbidden
- The access privileges were insufficient for the action that the API function tried to perform. See the next section on authorization for a way to fix this.
- 500 - Internal Server Error
- The Control Center had problems handling the request. Please, report this as a bug.
API calls can be performed as any user, by authenticating with that user's name and password. If no user name is provided, the API call is performed as the
The privileges required to perform a call depend on the actions done by that call: to get information
guest access is enough, for starting jobs
user access is needed and for changing definitions
operator access is required. This is consistent with the privileges required for actions done via the web interface.
By default the user
api does not have any access rights at all. If you want to allow unauthenticated API calls in your factory, change the role of the user
api. This can be done on the Control Center, under Configure / Users.
Doing an HTTP Request
When writing a wrapper as a batch file, shell script or Makefile, we recommend the command line tool wget. This tool is easy to script and it displays the full HTTP status line, so you can see the error message if something goes wrong. A typical 'wget' command line looks like this:
wget -O resultfile http://ControlCenterURL/FunctionWithArguments
Or if you use authentication:
wget -O resultfile --http-user=name --http-password=pass http://ControlCenterURL/FunctionWithArguments
part of script language - HTTP library
In other wrapper languages, you can use the respective standard library to do HTTP requests. Read this perl article about HTTP requests in perl, or this python article about HTTP requests in the python script language.