Task Management SOAP web services
The Task Management SOAP web service performs task query and update operations, including creating relationships and work information. It facilitates the exchange of data between the Change Management and ITSM Configuration Management applications.
Use the TMS:TaskInterface form in the Task Management System (TMS) to perform the following actions:
- Query tasks, relationships, and work information.
- Update tasks and work information.
The TMS:TaskInterface form is a self join of the TMS:Task form. It provides the server side filter functionality available with TMS:Task. It is used extensively to support web services.
Web services is one of the protocols that leverages this interface form. You can use the TMS:TaskInterface form with other protocols like API, other AR System applications, and so on, to perform specific operations. By itself, the interface form does not support the relationships and work information actions that are available through the web service operations.
The TMS web services feature extends to allow creation of multiple task relationships. The TMS:RelationshipsInterface_Create interface form supports the creation of task relationships.
Web service function overview
The TMS_TaskInterface web service is used to let ITSM Configuration Management query and update tasks. A back-end task web service interface form acts as a web service interface into the task entry. This form handles both returning values for queries from ITSM Configuration Management and updating data directly to the task entry. It also handles updating data that is related to the task entry, such as work information or associations.
The TMS_TaskInterface web service is a complex web service with many operations. It is based on the TaskInterface.xsd XML schema, which is also provided for advanced users who want to extend and modify the out-of-the-box web service. For more information about web services, see
Publishing the AR System functionality as a web service
.
The following web service functions are available for the Task Management module.
- QueryTaskPlusRelationshipsAndWorkInfo—Returns the most detailed information. This function queries tasks, relationships, and work information.
- QueryTaskOnly—Queries only tasks.
- QueryTaskPlusWorkInfo—Queries tasks and work information.
- QueryTaskPlusRelationships—Queries tasks and CI relationships.
- UpdateTaskOnly—Updates only tasks.
- UpdateTaskAndWorkInfo—Updates tasks and work information.
In the Query operations and in the UpdateTaskOnly operation, the input parameter is the Task ID.
For the UpdateTaskAndWorkInfo operation, the main input parameter is the Task ID. Existing work information records can be updated if their Instance ID is provided.
Finally, you can use the UpdateTaskAndWorkInfo operation to create new work information entries for existing tasks if the work information Instance ID is omitted. Even though you do this procedure by using the same operation that updates a task in general, creating new work information entries for existing tasks is its own specific function.
Application and task integrations
You can use two main integration points with tasks. The primary integration point for TMS uses the TMS:TaskInterface form. Web services have been established to support queries, updates, and limited create operations.
Launching outbound communication with tasks is supported by using the following mechanisms:
- For more comprehensive solutions, you can leverage CAI to trigger outbound communication. CAI lets you provide task parameters that integrate with your applications with the following protocols:
- Web services
- URLs
- AR protocol (used for the BMC Helix ITSM applications)
- Command line
- Plug-in
- You can create new automatic tasks that are self-contained structures. For example, you can create a workflow with a task and then fork a process to run a command that interacts with another application or program.
Runtime tasks instantiated from automatic task templates are intended to run automatically without human intervention. You can assign a task assignee to monitor them, but it is not required. Seven automatic tasks are already created for you to use. If you need a different automatic task, you must define a new automatic command. All automatic commands have specific workflows on the TMS:Task form that trigger the needed function. All the specific automatic task filter workflows exist within an execution order of 300 and 399-305 is the minimum and 397 is the maximum range for adding filters for new automatic tasks. (The set from 398399 are used for setting the appropriate status.)
In addition, outbound automatic tasks can use a web service filter.
Do not confuse an automatic task with a manual task. Define all the content that you need to create an automatic task on the Automatic tab of the Task Template form. Do not create an automatic task with any details that imply a human should intervene anywhere in the process. Automatic tasks, when activated, attempt to perform whatever work they are defined to do. When automatic tasks run, they have only two possible states:
- Complete—Their status is Closed with a relevant status reason.
- Waiting—They are in this status until they reach the Complete state.
Never define a Launch command with an automatic task. Using the Launch command always implies human intervention. For more information about defining automatic commands, see Creating task templates.
Tip
Using the CAI method or creating new tasks from scratch, depends on whether your primary need is ease-of-use or flexibility. The CAI option only requires data entries for outbound communication with tasks. With new automatic tasks, you have maximum flexibility, but at the cost of some complexity. You still must create your own workflow for them to operate properly.
Query operations
You can use the following query functions that are specific to web services.
- QueryTaskPlusRelationshipsAndWorkInfo
- QueryTaskOnly
- QueryTaskPlusWorkInfo
- QueryTaskPlusRelationships
To perform a search outside of web services, do it directly from the TMS:TaskInterface form.
The following table lists the input values from the TMS:TaskInterface form:
DB field on interface form | Web service field | Notes |
|---|---|---|
TaskID | TaskID | Supply Task ID as the input parameter |
The following table lists the output values from the TMS:TaskInterface form:
DB field on interface form | Web service field |
|---|---|
TaskID | TaskID |
InstanceId | TaskInstanceID |
Status | TaskStatus |
StatusReasonSelection | TaskStatusReason Selection |
RootRequestID | RequestID |
RootRequestInstanceID | RequestInstanceID |
RootRequestName | RequestName |
TaskType | TaskType |
TaskName | TaskName |
Summary | TaskSummary |
Notes | TaskNotes |
Priority | Priority |
RootRequestLevel | RequestLevel |
Assignee Company | AssignedCompany |
Assignee Organization | AssignedOrganization |
Assignee Group | AssignedGroup |
Assignee | Assignee |
Scheduled Start Date | ScheduledStartDate |
Scheduled End Date | ScheduledEndDate |
Actual Start Date | ActualStartDate |
Actual End Date | ActualEndDate |
EffortTrackingStartTime | EffortTrackingStartTime |
EffortTrackingEndTime | EffortTrackingEndTime |
BudgetEstimatedTotalTime | BudgetEstimatedTotal Time |
ActualEstimatedTotalTime | ActualEstimatedTotal Time |
AutoCostCalculationUnitType | AutoCostCalculation UnitType |
Activate Time | ActivateTime |
Assign Time | AssignTime |
EndTime | EndTime |
Location Company | LocationCompany |
Region | Region |
Site Group | SiteGroup |
Site | Site |
Company | RequesterCompany |
First Name | RequesterFirstName |
Middle Name | RequesterMiddleName |
Last Name | RequesterLastName |
Phone Number | RequesterPhoneNumber |
Organization | RequesterOrganization |
Department | RequesterDepartment |
Support Organization | SupportOrganization |
Support Group Name | SupportGroupName |
Customer Company | CustomerCompany |
Customer First Name | CustomerFirstName |
Customer Middle Name | CustomerMiddleName |
Customer Last Name | CustomerLastName |
Customer Phone Number | CustomerPhoneNumber |
Customer Organization | CustomerOrganization |
Customer Department | CustomerDepartment |
Product Cat Tier 1 | ProductCategorization Tier1 |
Product Cat Tier 2 | ProductCategorization Tier2 |
Product Cat Tier 3 | ProductCategorization Tier3 |
Product Name | ProductName |
Product Model/Version | ProductModelVersion |
Manufacturer | Manufacturer |
Operational Cat Tier 1 | Operational CategorizationTier1 |
Operational Cat Tier 2 | Operational CategorizationTier2 |
Operational Cat Tier 3 | Operational CategorizationTier3 |
attachmentName | Attachment1Name |
attachmentData | Attachment1Data |
attachmentOrigSize | Attachment1OrigSize |
attachmentName | Attachment2Name |
attachmentData | Attachment2Data |
attachmentOrigSize | Attachment2OrigSize |
attachmentName | Attachment3Name |
attachmentData | Attachment3Data |
attachmentOrigSize | Attachment3OrigSize |
Character 01 | Character01 |
Character 02 | Character02 |
Character 03 | Character03 |
Character 04 | Character04 |
Character 05 | Character05 |
Character 06 | Character06 |
Integer 01 | Integer01 |
Integer 02 | Integer02 |
Integer 03 | Integer03 |
Real 01 | Real01 |
Real 02 | Real02 |
Real 03 | Real03 |
Decimal 01 | Decimal01 |
Decimal 02 | Decimal02 |
Date 01 | Date01 |
DateTime 01 | DateTime01 |
DateTime 02 | DateTime02 |
Time 01 | Time01 |
YesNo 01 | YesNo01 |
YesNo 02 | YesNo02 |
On 01 | On01 |
On 02 | On02 |
AutomaticCommandSelection | AutomaticCommand |
ElectronicField1 | ElectronicField1 |
ElectronicField2 | ElectronicField2 |
ElectronicField3 | ElectronicField3 |
ElectronicText | ElectronicText |
ElectronicDecimal | ElectronicDecimal |
TimeOutValue | TimeOutValue |
Unit | TimeOutUnit |
ExpectedTimeOut | ExpectedTimeOut |
The following table lists the output values from the TMS:Relationships form:
DB field on interface form | Web service field |
|---|---|
Relationships ID | RelationshipsID |
InstanceID | RelationshipsInstanceID |
Status | RelationshipsStatus |
RelatedItemID | RelatedItemID |
RelatedItemSource | RelatedItemSource |
RelatedItemType | RelatedItemType |
Description | Description |
Attribute1 | Attribute1 |
Attribute2 | Attribute2 |
Attribute3 | Attribute3 |
RelationshipType | RelationshipType |
The following table lists the output values from the TMS:WorkInfo form:
DB field on interface form | Web service field |
|---|---|
InstanceID | WorkInfoInstanceID |
Status | WorkInfoStatus |
WorkInfoType | WorkInfoType |
Communication Source | WorkInfoCommSource |
Summary | WorkInfoSummary |
Notes | WorkInfoNotes |
Secure Log | WorkInfoSecureLog |
attachmentName | WorkInfoAttachment1Name |
attachmentData | WorkInfoAttachment1Data |
attachmentOrigSize | WorkInfoAttachment1OrigSize |
attachmentName | WorkInfoAttachment2Name |
attachmentData | WorkInfoAttachment2Data |
attachmentOrigSize | WorkInfoAttachment2OrigSize |
attachmentName | WorkInfoAttachment3Name |
attachmentData | WorkInfoAttachment3Data |
attachmentOrigSize | WorkInfoAttachment3OrigSize |
Modify operations
You can use the following modify functions that are specific to web services:
- UpdateTaskOnly updates only tasks.
- UpdateTaskAndWorkInfo updates tasks and work information.
To execute a modify function outside of web services, do it directly from the TMS:TaskInterface form.
The following table lists input values for the TMS:TaskInterface form:
DB field on interface form | Web service field |
|---|---|
TaskID | TaskID
|
Summary | TaskSummary |
Notes | TaskNotes |
Priority | Priority |
RootRequestLevel | RequestLevel |
Scheduled Start Date | ScheduledStartDate |
Scheduled End Date | ScheduledEndDate |
Actual Start Date | ActualStartDate |
Actual End Date | ActualEndDate |
EffortTrackingStartTime | EffortTrackingStartTime |
EffortTrackingEndTime | EffortTrackingEndTime |
BudgetEstimatedTotal Time | BudgetEstimatedTotal Time |
ActualEstimatedTotal Time | ActualEstimatedTotal Time |
AutoCostCalculation UnitType | AutoCostCalculationUnit Type |
Location Company | LocationCompany |
Region | Region |
Site Group | SiteGroup |
Site | Site |
attachmentName | Attachment1Name |
attachmentData | Attachment1Data |
attachmentOrigSize | Attachment1OrigSize |
attachmentName | Attachment2Name |
attachmentData | Attachment2Data |
attachmentOrigSize | Attachment2OrigSize |
attachmentName | Attachment3Name |
attachmentData | Attachment3Data |
attachmentOrigSize | Attachment3OrigSize |
ElectronicField1 | ElectronicField1 |
ElectronicField2 | ElectronicField2 |
ElectronicField3 | ElectronicField3 |
ElectronicText | ElectronicText |
ElectronicDecimal | ElectronicDecimal |
TimeOutValue | TimeOutValue |
Unit | TimeOutUnit |
ExpectedTimeOut | ExpectedTimeOut |
The following table lists the input values from the TMS:WorkInfo form:
DB field on interface form | Web service field |
|---|---|
InstanceId | WorkInfoInstanceId
|
InstanceID | WorkInfoInstanceID |
WorkInfoType | WorkInfoType |
Summary | WorkInfoSummary |
Secure Log | WorkInfoSecureLog |
WorkInfoDate | WorkInfoDate |
Communication Source | WorkInfoCommSource |
Notes | WorkInfoNotes |
Secure Log | WorkInfoSecureLog |
attachmentName | WorkInfoAttachment1 Name |
attachmentData | WorkInfoAttachment1Data |
attachmentOrigSize | WorkInfoAttachment1OrigSize |
attachmentName | WorkInfoAttachment2 Name |
attachmentData | WorkInfoAttachment2Data |
attachmentOrigSize | WorkInfoAttachment2 OrigSize |
attachmentName | WorkInfoAttachment3 Name |
attachmentData | WorkInfoAttachment3 Data |
attachmentOrigSize | WorkInfoAttachment3 OrigSize |
Comments
Log in or register to comment.