BMC Helix ITSM
NOTE: End of Support for SOAP API
Last Updated:
Planview has discontinued support for BMC Helix ITSM integrations using SOAP API. If you are currently using SOAP API, you must migrate your Hub instance to REST API. If you need assistance migrating from SOAP to REST, please contact customer care.
Upgrading to 22.3 and later: Upon upgrading, you may notice that previous BMC Helix ITSM SOAP integration(s) result in a 404 Error that blocks migration. This is a result of the SOAP deprecation. Migration can only occur after the new REST address is provided in Hub.
Note: Please do not check “Use REST API” as this field has been deprecated and will produce errors if checked on the UI.
Once the new endpoint has been entered, the information saved, and the migration complete, the integration(s) should work as expected.
Note: You may need to manually trigger the migration event if you do not want to wait for the job to retry.
Overview
BMC Helix ITSM (formerly BMC Remedy) is an enterprise ITSM tool that deals with the planning, provisioning and management of IT services.
Being responsive is the cornerstone of providing excellent customer service. And to be responsive to customer needs, service desk professionals need a seamless communication channel with their colleagues in development. But without integrating the tools that these teams use, they are forced into using low-fidelity communication tools such as email and spreadsheets to collaborate on customer issues.
However, by integrating BMC Helix ITSM with the tools the development teams use, efficiency, productivity and cross-team visibility is increased and customer service is enhanced.
For Example:
- Let’s say your development team uses IBM EWM for defect management, while your support team prefers using BMC Helix ITSM for incident and problem management.
- The service desk uses BMC Helix ITSM to record incoming calls as incidents, escalating them to problems if the issue is an actual defect.
- Defects get synchronized over to IBM EWM for the development team to work on.
- If the development team requires more information about the problem, the teams can easily transfer comments and attachments back and forth.
- Fixed defects are updated and the resolution is communicated back to the support team.
Key Features and Benefits
- Synchronizes problems to preferred defect management tools
- Allows simple and convenient communication via attachments and comments
- Ensures changes in BMC Helix ITSM are instantly recorded in the development teams tool of choice
- Enhances customer satisfaction by giving support professionals information they need to respond to inquiries
- Ensures progress done on the artifacts are up to date in all tools
- Improves quality of IT services by closely integrating support with other teams
- Transforms customer support and issue/defect management into a seamless and integrated process
Supported Extensions
Smart IT
Planview Hub: 18.3.1 and later
Tasktop Sync: 4.15.0 and later
The BMC Helix ITSM connector supports use of BMC Helix ITSM 9 with Smart IT add-on 1.6.00.
Connector Setup Details
This section describes the basic steps needed to prepare your BMC Helix ITSM instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.
Minimal User Permissions & Hub User
We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization.
In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.
Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'
See instructions on how to create a new user in BMC Helix ITSM.
List of minimal user permissions:
- User must have sufficient permissions to create and update artifacts in BMC Helix ITSM (and therefore read/write access to the corresponding forms associated with those artifact types)
For REST connections to Helix ITSM versions below 18.08, users must additionally have read access to the following forms:
- AR System Metadata: field
- AR System Metadata: field_char
- AR System Metadata: arschema
Note: If the user has admin permissions or has been granted Unrestricted Access, no additional steps are needed to enable permissions for these forms.
To support integration of Changes for REST connections to BMC Helix ITSM, the user must have additionally have the following permissions:
- read access for the Location Company field on the COM:Company form.
- This is needed to determine values for Company and Location Company fields on Change artifacts.
Note: If the user has admin permissions or has been granted Unrestricted Access, no additional steps are needed to enable permissions for these forms. Some preexisting permissions groups may also already include this permission.
In order to determine if a user has the permission, or to add the permission, this can be accessed in the UI via: AR System Administration > AR System Administration Console > Application > Users/Groups/Roles > Users > Group List.
The permission for the field will appear in the group list based on its field ID, which is '1000000001'.
For Incident creation on REST Connections to BMC Helix ITSM, creator impersonation (setting the submitter field on a newly created artifact to a user other than the Hub user) for the Incident artifact type is only supported if the Hub user has admin permissions or the unrestricted access permission. This is due to a current defect in BMC Helix ITSM.
Connecting to the BMC Helix ITSM Repository
Standard Authentication
Required Fields:
- Location/Connection URL
- Example Format:
- https://<localhost>:<port>/api (REST API)
- By default, port is 8008.
- Port can be found in this file:
- BMC 9.0 - 9.1.03:
C:\Program Files\BMC Software\ARSystem\jetty\etc\jetty-selector.xml - BMC 9.1.04+:
C:\Program Files\BMC Software\ARSystem\jetty\etc\jetty-http.xml
- BMC 9.0 - 9.1.03:
- https://<localhost>:<port>/api (REST API)
- Example Format:
- Username
- Password
Optional Fields:
- AR System Server: This field has been deprecated as SOAP API is no longer supported.
- Use REST API: This field has been deprecated and will produce errors if checked on the UI.
- Substitute Artifact Location
- Available in Planview Hub 19.2.11+/ 19.3.0.20190705 and later, Tasktop Sync 4.19 and later.
- Only for REST API or Smart IT.
- See details below.
- Attachment Gateway Location: Specifies an attachment base URI when the REST repository is behind a gateway or proxy. See details below.
- Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
- Connection Security: When enabled, insecure connections to this repository will be allowed. See details here.
Substitute Artifact Location
Due to a repository limitation, Hub does not have sufficient information to build the correct artifact location field for REST without the Substitute Artifact Location field being filled out on the Helix ITSM repository connection screen. This field essentially "overrides" the default artifact location field, so that Hub can create a valid URL for REST.
There are two "placeholders" that must be used to correctly format the input for this field:
-
_identifier_ for the regular Helix ITSM UI
-
_smart_it_identifier_ for the Smart IT UI (for Hub 19.3+ only)
These placeholders signify where in the URL the identifying information about an artifact goes.
Substitute Artifact Location format:
- For REST API: http://<host and port of Mid Tier Location>/arsys/forms/<AR system location>/_identifier_
- For Smart IT on REST: <Smart IT Location>/_smart_it_identifier_ .
- The <Smart IT Location> might look like the following:
- http://<host and port>/ux/smart-it
- http://<host and port>/smartit
- The <Smart IT Location> might look like the following:
SSO Authentication
Additionally, BMC Helix ITSM supports the following SSO implementations:
- CA Siteminder/CA Single Sign-On (HTTP POST)
- CA Siteminder/CA Single Sign-On (Login Form)
- Script (HTTP cookies)
- X.509 Certificate
Learn more about how to set up your repository in Planview Hub here.
Initialization and Change Queries (Tasktop Sync)
Tasktop Sync uses queries in the ALM systems to determine the artifacts to synchronize and detect changes in the system.
The initialization query represents the full set of artifacts to synchronize and is only run on initial configuration or manually.
The changes query should be defined the same as the initialization query but include some time scoping information (e.g. last 7 days) as this is the query that is executed on the defined schedule to detect changes. In many cases, these queries can be defined in the ALM system, providing the power of the built-in filters to properly scope the synchronization. If this is not possible, Tasktop Sync provides other mechanisms for filtering items in scope.
The BMC connector offers various query types for you to retrieve items from the repository. Most flexible one will be server query language based search and you can find details for that below.
|
Query |
Instruction |
|---|---|
|
Initialization Query |
For initializations query, choose to either use server query language type query or artifact type query. For example, you could retrieve all Incidents and further filter them.
|
|
Changes Query |
For changes query it is advised to only return a subset of items, therefore, choose to use the "Recently modified" query.
|
Creating a Server Query Language Query
The query returns a subset of artifacts matching the user-defined query string. The individual query strings should be in the format of ‘{field-id}’{operator}“{field-value}”. Multiple query strings could be combined using conditional operators.
-
field-id: the Field ID of the field in Helix ITSM Developer Studio. In the below example, Assigned Group’s Field ID is 1000000217, and Assigned Group ID’s Field ID is 1000000079.
- operator: the types below refer to the XML Data Type in the web services.
- string fields: =, !=
- dateTime and date fields: >=, <=, <, >, =, !=
- int, integer, decimal, double, and float fields: >=, <=, <, >, =, !=
- field-value: the value to query for.
- conditional operators: and, or, (, )
Date/Time field values are interpreted based on the locale setting of the user account used to connect to the repository. Refer to BMC Helix ITSM documentation for a description of the supported date and time formats.
Examples:
- All artifacts that have been assigned to the “Service Desk” or “Frontoffice Support” groups: ‘7’=“Assigned” and (‘1000000217’=“Service Desk” or ‘1000000217’=“Frontoffice Support”)
- All artifacts that have not been modified since January 1, 2015: ‘6’<="2015/01/01 00:00:00"
Note: Not all fields of all artifact types are query-able.
Other Configuration Settings
REST API
Planview Hub: 19.2.2 and later
Tasktop Sync: 4.18.2 and later
BMC Helix ITSM: 9.0 and later
Note: Please contact support for assistance in migrating from SOAP to REST API.
The BMC Helix ITSM connector has historically used Helix ITSM's SOAP API for all connector operations against a Helix ITSM repository. This method of connecting required that the BMC Helix ITSM admin install a set of custom webservices on their Helix ITSM server, created and maintained by Hub.
The Helix ITSM Connector now allows customers to connect to Helix ITSM via its REST API. This means that the custom webservices are no longer needed when connecting using this method.
In addition to eliminating the need for custom files and webforms, the REST API is also more performant. Note that some future features may only be available on REST.
Beginning in April 2022, Hub has discontinued support for BMC Helix ITSM integrations using SOAP API.
Configuration
Hub Configuration
Assuming REST is already properly enabled in BMC Helix ITSM (please see section below for more details), you can follow the steps below to configure BMC to use the REST API within Hub:
From Hub's perspective (in Hub or Sync), switching a Helix ITSM repository connection from SOAP to REST only involves providing a valid REST URL for Helix ITSM in the Location field.
Note: The 'Use Rest API' field has been deprecated as Hub has deprecated support for SOAP.
Within the same repository, there is often a different endpoint for REST than for SOAP. For REST, you will most likely need to provide the alternate endpoint.
The Location/URL will follow the format: https://<localhost>:<port>/api
Port can be found in this file:
- BMC 9.0 - 9.1.03:
C:\Program Files\BMC Software\ARSystem\jetty\etc\jetty-selector.xml - BMC 9.1.04+:
C:\Program Files\BMC Software\ARSystem\jetty\etc\jetty-http.xml
By default, Helix ITSM uses port 8008
-
- A port change or SSL activation/deactivation will require a service restart (restart BMC Helix ITSM Action Request System Server)
BMC Helix ITSM Configuration
From a Helix ITSM configuration standpoint, in order to facilitate connecting to Helix ITSM using REST there are two other prerequisites specific to this method:
- The Helix ITSM repository must have REST enabled and have proper security configuration
- The Helix ITSM repository will have REST enabled (for appropriate versions), however it is by default enabled with SSL. Thus, you will either have to import appropriate certificates or configure HTTP without SSL (a faster option for internal or testing infrastructure).
- Please follow configuration steps for Helix ITSM REST, found here
- Several fields must be made available on the Helix ITSM (non-custom) forms used by Hub which are not, by default, available out of the box
Necessary modifications to Helix ITSM forms
Not all fields that have been made available via Hub's customized webservices are available by default on Helix ITSM's forms. This means that customers must make configuration changes to their Helix ITSM servers in order to enable some functionality.
Important: For Hub versions earlier than 19.3.0.20190603, In order to synchronize the 'Change' artifact type, the field 'Last_Modified_Date' (field id '6') must be added to the 'CHG:ChangeInterface' form.
If the following fields aren't added to the associated form in Helix ITSM, the field will not be available for mapping:
For Artifact Type: 'Work Order', in order to use the following field it must be added to the 'WOI:WorkOrderInterface' form:
- Vendor_Ticket_Number (field id '1000000652')
For Artifact Type: 'Change', in order to use this field it must be added to the 'CHG:ChangeInterface' form:
- Change_Implementer (field id '1000003258')
Instructions for adding a field to a form overlay:
- Open the form from the Forms view
- Select "Form"->"Create View Overlay" from the main menu and confirm when the dialog appears.
- Right-click the form and select "Add Fields from CHG:Infrastructure Change"
- Select the new field from the list of items and click OK.
- Select the newly added field on the form and open the Properties view.
- Expand the "'Database" and "Join Information" sections.
- Update "Name" and "ID" on the "Database" section to match the "Join Information" section
Migration from SOAP to REST
Customers are able to convert existing integrations from SOAP to REST with minimal impact.
In order for Planview Hub to complete a migration between SOAP to REST, the following steps should be taken:
- Stop any running integrations
- On the Repository Connection screen for Helix ITSM, enter a valid REST API URL in the 'Location' field and save the changes
- Shut down and restart Hub (this triggers a refresh of all fields available for mapping)
- For each Helix ITSM collection, verify the field mappings are correct (see 'Changes when moving from SOAP to REST')
- Restart the previously stopped integrations
Changes when moving from SOAP to REST
Planview Hub: 19.2.2 - 19.2.10, 19.3.0 - 19.3.1
Tasktop Sync: 4.18.2 - 4.18.10
BMC Helix ITSM: 9.0 and later
Note: Due to a Helix ITSM API limitation, the 'location' field does not work as expected for Helix ITSM REST in the versions listed above. This means that the (source/target) Artifact link on the Activity screen points to an invalid location, and if the location field were to be mapped it would have that same invalid value. A fix is available in subsequent versions of Hub.
Custom Fields in SOAP
Note: Until version 20.1/4.21, Hub did not officially support custom fields for the Helix ITSM connector, or any modifications a user might make to the webservice definition files provided for installation.
Despite this, some users may have modified their webservice definition files to add their own fields.
Upon migration from SOAP to REST, custom fields may be lost due to differences in how the SOAP and REST APIs represent field labels and IDs. To remedy this, we recommend remapping any custom fields when migrating from SOAP to REST.
Note that in Hub versions earlier than 20.1/4.21, it may not be possible to re-add custom fields that were lost during migration.
Field Labels
All field labels will be updated upon migration from SOAP to REST.
Planview Hub: 19.2.4 and later
Tasktop Sync: 4.18.4 and later
BMC Helix ITSM: 18.08 and later
Previously in SOAP, field labels exposed by the connector corresponded to the hard-coded values provided in the custom webservice definitions.
In REST, field labels exposed by the connector will directly correspond to the 'display label' shown in the Helix ITSM UI, for the Hub and Helix ITSM versions outlined above.
Please be aware of the following limitations within BMC Helix ITSM:
- 'Display Labels' are attached to 'views' of a given artifact (form), of which there can be many views for one artifact.
- Fields might exist on the artifact/form but not in any views
As a result, when determining which field labels to surface the connector will do the following:
- It will only consider display labels for fields found on the 'default admin view' that comes out-of-the-box with Helix ITSM installations
- If a field has a display label on the default admin view, and that display label is different from the database name for that field, the connector will display the field label as 'Display Label (Database Name)'
- If a display label could not be found, or if the display label is the same as the database name, the connector will display the field label as 'Database Name'
Some examples:
-
Field has display label 'Assignee Support Company' and database name 'ASCPY'. This will appear in Hub as 'Assignee Support Company (ASCPY)'
-
Field has display label 'Submit Group' and database name 'Submit Group'. This will appear in Hub as 'Submit Group'
-
Field has database name 'Requested_Start_Date' and a display label could not be found on the 'default admin view'. This will appear in the connector as 'Requested_Start_Date'
Planview Hub: 19.2.3
Tasktop Sync: 4.18.3
or later versions of Hub with BMC Helix ITSM versions earlier than 18.08
Previously in SOAP, field labels exposed by the connector corresponded to the hard-coded values provided in the custom webservice definitions.
In REST, field labels exposed by the connector directly correspond to the 'database name' property of that field on its form in Helix ITSM.
This document provides a list of SOAP field names and their corresponding default REST field database name: Helix ITSM Field Labels SOAP vs REST.xlsx
Removal of Duplicate Fields
Some of the fields provided by the Helix ITSM connector via SOAP were duplicated, in that they pointed at the same underlying field in Helix ITSM as other fields with different names.
In REST, one field from each of these duplicated 'field pairs' will be removed.
For Work Orders:
- 'First_Name' is removed, which duplicates the field: 'Contact_First_Name'
- 'Last_Name' is removed, which duplicates the field: 'Contact_Last_Name'
- 'Phone_Number' is removed, which duplicates the field: 'Contact_Phone_Number'
For Problems:
- 'Assigned_Group_Pblm_Manager' is removed, which duplicates the field: 'Problem_Coordinator_Assigned_Group'
All values identified above reflect the labels of those fields as they exist today in SOAP.
Removal of the Status History field on Work Orders
The read only field 'Status-History' on Work Orders (field id '7') will not appear when connecting to Helix ITSM via REST.
This field did not work as intended in SOAP and is presently not supportable in Helix ITSM REST.
Field Dependencies
Helix ITSM REST has some field dependencies to be aware of when configuring and running integrations:
On Work Orders:
REST field name: Support Group Name (UI/SOAP field name: Manager Support Group Name)
- This field is part of a hierarchical chain: Support Company → Support Organization → Support Group
- Helix ITSM does not require the entire hierarchy to be written to when updating the Support Group field
- This field is a writeable single select field in REST
REST field name: ASGRP (UI/SOAP field name: Request Assignee Support Group Name)
- This field is part of a hierarchical chain: Support Company → Support Organization → Support Group
- For this set of fields,
- Support Company = ASCPY
- Support Organization = ASORG
- Support Group = ASGRP
- This field dependency is expressed by the connector to Hub
- Helix ITSM requires all three values of the hierarchy to be written to when updating the Support Group field
- If the Support Group field is written to without the Organization and Company fields, this error message will be thrown:
- "ASGRP" has a value but depends on "ASORG" that has no value set.
- All three fields have been changed in REST to writeable single select fields
Request Assignee (REST and SOAP/UI field name)/ CAB Manager Login (UI/SOAP: Request Manager)
- These fields are writeable person fields in REST
- The person in these fields must be a valid assignee of the selected support group
- Each support group has a number of users which are available to be assigned to it
- The ASGRP field corresponds to the Request Assignee field
- The Support Group Name field corresponds to the CAB Manager Login field
- If the person is not a valid assignee, this error message will be thrown:
- Unable to communicate with repository. Error processing response (HTTP 500: Internal Server Error): ERROR: The Request Assignee Group fields are invalid. Use the menus for the Support Company, Support Organization, Support Group Name, and Request Assignee fields to select this information.
Custom Field Configuration for Required Fields
If you would like to add required custom fields that are supported by BMC Helix ITSM Developer Studio, please use the following instructions. Note that these instructions only apply to Incidents, Problems, Changes, and Work Orders; they do not apply to Tasks.
- If the field exists on the base form but not on the Interface_Create form, you will need to recreate the field on the Interface_Create form with the same name, Database ID, and properties as those listed on your base form.
- All required fields need to be pushed from the Interface_Create form back to the base form. To do this, you will need to modify your filters:
- For Incidents, select filter HPD:HII:CreateIncident_100`!
- For Problems, select filter PBM:PI:CreateProblem_100`!
- For Changes, select filter CHG:ICI:CreateChange_100`!
- For Work Orders, select filter WOI:WIC:CreateWorkOrder_100`!
- Open the selected filter and expand the 'If Actions → Push Fields' section.
-
- Scroll to the table of field mappings and select 'Auto Map.'
- A dialog will appear with suggestions. Select 'Match IDs.'
-
- Remove all extra suggested fields until only the desired fields are listed. If a field is missing, check that its Database ID matches in both the base form and Interface_Create form.
- Select 'OK' to add the field mappings.
- Adding field mappings allows BMC Helix ITSM to view the required fields on the artifact creation schema and enables BMC Helix ITSM to write to the required fields on artifact creation.
If you choose not to follow these instructions, you must configure all required custom fields on the base form with default values. If you do not configure a default value, Planview Hub will not be able to create any new artifacts.
Reverse Proxy/Gateway Configuration
There is some configuration required to use BMC Helix ITSM behind a reverse proxy/gateway.
You must set Attachment Gateway Location on the Repository Connection screen.
- This should map to the same endpoint as the Location field.
- This will most likely be the same value.
For the Attachment Gateway Location field to work, the following requirements must be met:
- Artifacts must be stored in the standard way in Helix ITSM.
- The Attachment Gateway Location must be used to replace the base segment of the absolute URL of the returned for the attachment.
Please note that the following logic is applied as the URL replacement strategy:
- Absolute URL
- www.my-remedy-host.com:8000/api/path/to/some/attachment
- Attachment Gateway Location
- www.path-to-gateway.com:8000/some/location
- Expected Attachment Location
- www.path-to-gateway.com:8000/some/location/path/to/some/attachment
- The host, port, and leading /api segment is replaced.
- www.my-remedy-host.com:8000/api/ is replaced with the field value.
Status Field Configuration
If the 'status' field is not updating in BMC Helix ITSM and you are not getting any error messages in Hub, follow the steps below to resolve the issue:
- Re-import the def file
- Flush the cache on the mid-tier
- Restart the app server
State Transitions
Planview Hub: 17.3 and later
Tasktop Sync: 4.11 and later
Below are some limitations to be aware of when configuring state transitions in BMC Helix ITSM:
- When setting up transition mappings into BMC Helix ITSM, Status on Creation setting should be set to Draft for Problem artifacts. Set to New for Incident artifacts.
- In BMC Helix ITSM, artifacts generally cannot transition out of a 'closed' state
- In BMC Helix ITSM, incidents can re-open, but this will duplicate the incident, leaving the original linked incident as 'closed.'
Comments
Planview Hub: All
Tasktop Sync: 4.0 and later
|
Planview Hub Versions |
Tasktop Sync Versions |
Comment Behavior |
|---|---|---|
|
19.3.0 and later |
4.19 and later |
Normal work info notes and work info notes generated via e-mail will be synchronized. Automatically generated work info notes (for example due to assignment or status changes) will be marked as 'synthetic comments' and ignored in integrations. In Tasktop Sync, 'Comment Content-Type' should be set to “text/plain”. |
|
Supported versions earlier than 19.3 |
Supported versions earlier than 4.19 |
Normal work info notes will be synchronized. Automatically generated work info notes (for example due to assignment or status changes) will be marked as 'synthetic comments' and ignored in integrations. Email comments are not handled/retrieved. In Tasktop Sync, 'Comment Content-Type' should be set to “text/plain”. |
Learn more about how to configure comment flow in Planview Hub here.
Attachments
Work Info Notes with file attachments will be synced over as attachments.
Learn more about how to configure attachment flow in Planview Hub here.
Person Reconciliation
For person reconciliation, the following fields are available:
|
Fields Used for Hub’s Default Person Reconciliation Algorithm |
Field Names for Person Reconciliation (Note that these are case sensitive) |
Label in BMC Helix ITSM |
|---|---|---|
|
ID |
person-id |
ID |
|
|
person-email |
Email Address |
|
Username |
person-username |
Username |
|
N/A |
person-first-name |
First Name |
|
N/A |
person-last-name |
Last Name |
|
N/A |
person-display-name |
Display Name |
Limitations for Person Reconciliation:
- Hub is unable to process users without login names. Therefore if a user in Helix ITSM does not have a login name, it will be ignored by Hub. This can apply to users such as Non-Support Staff users or Customers.
- If you would like to pull a field such as the Customer Name from BMC Helix ITSM, the following workaround is available: Instead of mapping the Customer person field directly, users can map string fields like Customer_First_Name, Customer_Middle_Name, and Customer_Last_Name. Similarly, when using a Person Reconciliation Extension, unresolvedPerson could contain useful fields such as email, first name, last name, and display name.
-
For Incident creation on REST Connections to BMC Helix ITSM, creator impersonation (setting the 'submitter' field on a newly created artifact to a user other than the Hub user) for the Incident artifact type is only supported if the Hub user has 'admin' permissions or the 'unrestricted access' permission. This is due to a defect in Helix ITSM.
Learn more about how to configure person reconciliation in Planview Hub here.
Full Scan
Due to third party API limitations, changes to the following fields may not trigger change detection or cause a synchronization immediately. To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:
- Attachments or Comments on Changes
- Attachments or comments added to Tasks via the API
Learn more about how to configure change detection and full scan intervals in Planview Hub here.
Supported Features
Special Features Supported
You can learn more about special features in Planview Hub here.
|
Feature |
Custom Type Supported? |
Applicable Hub Version |
Applicable Repository Versions |
Default Maximum Size in Repository |
|---|---|---|---|---|
|
|
|
|
|
|
|
(Planview Hub: 22.3 and later & Tasktop Sync: 4.31 and later) |
N/A |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
N/A |
|
|
N/A |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
2GB Learn more about maximum attachment size here. |
|
|
|
Planview Hub: 17.3 and later Tasktop Sync: 4.11 and later |
Any supported repository version: |
N/A |
Time Worked (Worklogs)
Supported Artifacts
Supported Work Items
Learn about the difference between containers and work items in Planview Hub here.
|
Supported Work Item Type |
Applicable Hub Versions |
Applicable Repository Version |
Unique URL? |
Limitations |
|---|---|---|---|---|
|
Problem |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
Yes |
|
|
Incident |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
Yes |
|
|
Change |
Planview Hub: 17.3 and later Tasktop Sync: 4.11 and later |
Any supported repository version: |
Yes |
|
|
Work Order |
Planview Hub: 17.3.4 and later Tasktop Sync: 4.11.4 and later |
Any supported repository version: |
Yes |
|
|
Task (must live under a Hub-supported artifact type) |
Planview Hub: 19.3.2 and later |
Supported versions using the REST API: |
Yes |
|
Supported Containers
Learn more about containment in Planview Hub here.
|
Containers that can synchronize between repositories |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
|
N/A |
|||
|
Containers used to define the boundary of a collection (when clicking 'Manage Projects' on a Collection) |
|||
|
N/A (entire repository serves as container) |
Planview Hub: All |
Any supported repository version: |
|
|
Containers used for artifact routing |
|
|
|
|
N/A (entire repository serves as container) |
Planview Hub: All |
Any supported repository version: |
Supported Field Types
Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.
|
Standard Field Type |
Does Hub support custom fields of this type? |
How is field type referenced in repository? |
Sample Repository Fields Supported |
Particular Repository Fields NOT Supported |
|---|---|---|---|---|
|
|
Planview Hub: 20.1 and later Tasktop Sync: 4.21 and later BMC Helix ITSM: REST API only |
Summary Temporary Workaround Site Site Group Region Product Name Organization Company Contact Company Assigned Group |
||
|
|
Planview Hub: 20.1 and later Tasktop Sync: 4.21 and later BMC Helix ITSM: REST API only |
Checkboxes |
Type Impact Investigation_Driver Priority Urgency Investigation_Status (read-only) Investigation_Status_Reason (read-only) Note that some Helix ITSM dropdown/single-select fields are treated as read-only string fields by Hub |
|
|
|
||||
|
|
||||
|
|
Planview Hub: 20.1 and later Tasktop Sync: 4.21 and later BMC Helix ITSM: REST API only |
Submit Date Last Modified Date |
||
|
|
Planview Hub: 20.1 and later Tasktop Sync: 4.21 and later BMC Helix ITSM: REST API only |
Target Date |
||
|
|
||||
|
|
Planview Hub: 20.1 and later Tasktop Sync: 4.21 and later BMC Helix ITSM: REST API only |
|||
|
|
Planview Hub: 20.1 and later Tasktop Sync: 4.21 and later BMC Helix ITSM: REST API only |
Priority Weight |
||
|
Note: Hub is unable to process users without login names. Therefore if a user (such as a Non-Support Staff user) in BMC Helix ITSM does not have a login name, it will be ignored by Hub. |
N/A |
|
||
|
|
||||
|
|
|
|
|
|
|
|
N/A |
Notes |
||
|
|
||||
|
|
Functional Limitations
|
Category |
Limitation |
Applicable Hub Versions |
Applicable Repository Version |
|---|---|---|---|
|
Third Party Functional Limitation |
Comments For some Helix ITSM artifacts, such as tasks, there is an option to select “(clear)” for the visibility of a comment. Setting a comment with that visibility bypasses Public/Internal visibility classification present in other Helix ITSM artifacts (e.g., Work Orders or Changes). This may result in unexpected behavior during artifact comment flow. |
Planview Hub: 22.3 and later Tasktop Sync: 4.31 and later |
|
|
Feature Unsupported |
Remedyforce The BMC Helix ITSM connector does not support the Remedyforce extension. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Configuration Requirement |
Product Model/Version Field Artifacts cannot be synchronized when Product Model/Version (or Closure Product Model/Version) is populated with a value and it's dependent fields Product Name and Product Categorization Tiers 1-3 are empty. To synchronize these artifacts, Product Model/Version options must exist for the corresponding Product. |
Planview Hub: All |
Any supported repository version: |
|
Third Party Functional Limitation |
Reverse Proxy/Gateway Support Proxy gateway support for attachments will only work when attachments are stored using the standard Helix ITSM methods and not stored in an external service. |
Planview Hub: 21.3 and later |
Any supported repository version: |
|
Configuration Requirement |
Comments and Attachments In order to create comments and attachments, the base form (e.g., for Incident, that would be HPD:Worklog) must have a default value on any required field that is not the 'workinfo' note or attachment file information. |
Planview Hub: All |
Any supported repository version: |
|
Feature Unsupported |
Formatted ID Search The BMC Helix ITSM connector does not support formatted ID search. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party Functional Limitation |
Projects Because BMC Helix ITSM does not support the notion of ‘projects,' the following behaviors may be observed when using Hub:
|
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Recently Modified Repository Query Settings The date format for the Planview Hub user in BMC Helix ITSM must be set to MM/DD/YYYY hh:mm:ss aa if using the recently modified repository query. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party Functional Limitation |
Field Database Names The Database Name of any Helix ITSM field should not be changed as the connector relies on these database names for certain field behaviors. A Helix ITSM field database name is distinct from a Helix ITSM field display label, in that they are not visible in the web UI and they are not impacted by localization. |
Planview Hub: 19.2.1 and later Tasktop Sync: 4.18.1 and later |
Any supported repository version: |
|
Third Party API Limitation |
Performance in Helix ITSM 18.08 There is a known defect in Helix ITSM 18.08 which prevents the connector from filtering down the number of field values retrieved upon artifact retrieval. This could have a minor performance impact on Helix ITSM integrations. The defect was resolved in 19.02. |
Planview Hub: 19.2.1 and later Tasktop Sync: 4.18.1 and later |
18.08 |
|
Third Party API Limitation |
Jetty Version Due to the Jetty version bundled with Helix ITSM 9.1.02/9.1.03, attachments on Helix ITSM artifacts larger than 5mb may not be successfully retrieved. BMC has confirmed that the Jetty version bundled with Helix ITSM 9.1.04+ does not have this limitation. |
Planview Hub: 19.2.1 and later Tasktop Sync: 4.18.1 and later |
9.1.02, 9.1.03 |
|
Third Party Functional Limitation |
Customer and Contact Fields Customer First Name, Customer Last Name, Customer Phone Number, and Customer Email fields are supported on Incidents as read-only fields. Contact First Name, Contact Last Name, Contact Phone Number, and Contact Email are supported on Incidents and Work Orders as read-only fields. These fields are read only in the connector to prevent users from altering person metadata at the artifact level in such a way that it conflicts with the underlying person entity's metadata. To synchronize these fields, the associated webforms must be installed on the BMC Helix ITSM server. |
Planview Hub: 19.1 and later Tasktop Sync: 4.17 and later |
Any supported repository version: |
|
Third Party API Limitation |
Date Fields Helix ITSM 8 does not correctly interpret time-zone information when querying with date fields. Users should give a 24 hour buffer when querying with date fields on Helix ITSM 8. |
Planview Hub: 18.3 and later Tasktop Sync: 4.15 and later |
Any supported BMC Helix ITSM 8.x version |
|
Third Party Functional Limitation |
Work Orders If the BMC field, 'Work Order Type' is set to a value other than Project or General, artifact creation in BMC Helix ITSM could fail. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Errors Helix ITSM returns a generic error message "ERROR (302): Entry does not exist in database" in varied situations such as authentication failure, no search results found, no work infos found, etc. The connector tries to discern the error's true meaning, but when it's not possible, the connector throws a ConnectorException with a generic error message. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Artifact Deletion Helix ITSM does not support artifact deletion through API but does allow background processes to delete. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Target Date Target Date is the only writable date field and it is sometimes required depending on the value of the Status field. This workflow info is not discoverable so the connector treats Target Date as a required date field regardless of Status value. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Field Management Several fields are presented as drop-downs in the Helix ITSM web UI but returned as string fields in the web services and there is not a way to discover their dropdown options. The connector implements these fields as read-only string fields. A few examples includes: "Assigned_Group", "Assigned_Support_Company", and "Assigned_Support_Organization". |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Field Management The Helix ITSM connector does not support setting the Assignee or Problem Coordinator fields on Problem artifact creation. The SOAP API ignores values in these fields when provided on artifact creation. Additionally, if the background job described above is turned on, it will automatically set values for these two fields immediately after creation. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Assignee Field The Helix ITSM connector does not support re-assigning the Assignee field on Incident artifacts. While the Web UI will allow this field to be modified, the SOAP API ignores values in these fields when provided after artifact creation. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Third Party API Limitation |
Field Management It is not possible to discover field display labels through web services. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Person Fields The Helix ITSM connector does not support setting a person field to a Helix ITSM person with a non-unique full name (first name + middle initial + last name). Using a person with a non-unique full name in a person field will result in a connector error upon retrieving the artifact. However, comment and attachment (i.e. Work Info) authors may be persons with non-unique full names. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Configuration Requirement |
Field Management Helix ITSM 9.1.00 Web Services does not support the ability to set an optional string field of an existing problem or incident to an empty or null value. This is a regression from 8.x. BMC has provided us with a patch for the issue. Eventually this patch will be rolled into a subsequent service pack against 9.1. Connector will only support Helix ITSM 9.1.00 with the patch applied. |
Planview Hub: All Tasktop Sync: 4.7 and later |
9.1.00 |
|
Configuration Requirement |
Work Info Field Connector only supports Helix ITSM 9.1.02 with patch 002 or newer installed. 9.1.02 with patch 002 has an outstanding BMC defect (ID SW00526418) that affects Tasktop_Incident_WorkInfo_WS and Tasktop_Problem_WorkInfo_WS. To work around the defect, the Incident_WorkInfo_QueryList and Problem_WorkInfo_QueryList operations must add "z2AF Work Log01/attachmentData", "z2AF Work Log02/attachmentData", and "z2AF Work Log03/attachmentData" to the Output Mapping. |
Planview Hub: All Tasktop Sync: 4.7 and later |
9.1.02 |
|
Third Party API Limitation |
Status Field Helix ITSM may not support changing the Status field on Problem artifacts on version 8. While the Web UI will allow this field to be modified, the SOAP API ignores values in these fields when provided after artifact creation. |
Planview Hub: 17.3 and later Tasktop Sync: 4.11 and later |
8.1.02 |
|
Configuration Requirement |
Submitter Field Helix ITSM Work Orders do not support modifying the Submitter field after it has been set. Users looking to map the Submitter field should configure the field to initialization only. |
Planview Hub 17.3.4 and later Tasktop Sync 4.11.4. and later |
Any supported repository version: |
|
Third Party API Limitation |
Invalid User When a user is deleted from the repository system but remains assigned to a Person field (for example, Request Assignee or Problem Coordinator) of an artifact, it may block the artifact from updating regardless of whether that field is mapped or not. If an artifact is blocked from updating, the best option will be to remove the deleted user from the assigned person fields. |
Planview Hub: 18.3 - 19.1.6 Tasktop Sync: 4.15 - 4.17.6 |
Any supported repository version: |